meles is a malware scanner for container images: one command on an image
reference, no Docker daemon, CI-friendly exit codes. In Kubernetes it also
scans every image your pods run and, if you want, holds new pods until their
image is scanned.
meles inspects what an image contains before it runs. It complements
vulnerability scanners and runtime detection such as Falco; it replaces neither.
The name comes from Meles meles, the European badger – it digs through the
layers.
What you get
CLI and CI:meles image <ref> fails a pipeline when it
finds malware. Output as table, JSON or SARIF, with
ignore rules for false positives.
Web UI: quick scans, cron schedules, run history and the
reports of the whole cluster.
Operator: scans the image of every pod and writes a
MalwareReport next to the workload, with optional Prometheus alerts.
Scan gate: optional, holds new pods per namespace until
their image is scanned, and pins the scanned digest.
Harbor: scans every pushed image as a pluggable scanner, also
chained with Trivy for one report.
TL;DR
Try it on your machine (Linux amd64, Docker, bash):
curl -fsSL https://github.com/movray/meles/releases/download/v0.3.3/meles_0.3.3_linux_amd64.tar.gz | tar -xz meles
docker run -d --name clamd -p 127.0.0.1:3310:3310 clamav/clamav:1.4
export MELES_CLAMD=tcp://127.0.0.1:3310
until (exec 3<>/dev/tcp/127.0.0.1/3310 && printf 'zPING\0' >&3 && head -c4 <&3 | grep -q PONG) 2>/dev/null; do sleep 5; done
./meles selftest
./meles image alpine:3.20
Or in a cluster (cluster admin, a default StorageClass, about 2 GB of free
memory on a node):
kubectl create namespace meles
kubectl label namespace meles pod-security.kubernetes.io/enforce=baseline
helm install meles oci://ghcr.io/movray/charts/meles --version 0.3.3 -n meles --set operator.enabled=true
kubectl -n meles rollout status deploy/meles-clamd --timeout=15m
kubectl get malwarereports -A # every image running in your cluster
kubectl -n meles port-forward svc/meles-server 8080:80 # http://localhost:8080/
The operator now pulls and scans the image of every pod, which counts
against the pull limits of your registries; it only reports and does not touch
your pods. Reports appear within minutes. A very large binary can end as
Incomplete, which is never clean: see
Reading the results.
The port-forward is only the quickest way to have a look. For permanent use,
expose the UI with server.ingress or server.httpRoute and put a login in
front of it with server.oauth2Proxy, all in the chart's values:
Login for the web UI. meles has no login of its
own, so do not expose the UI without one.
A step-by-step tour, from a file hidden by a later layer to the scan gate in
Kubernetes: docs/getting-started.md.
Why
Image scanners usually cover vulnerabilities, misconfigurations and secrets;
meles adds malware detection.
meles scans every layer separately, not just the final filesystem. A file
that a later layer deletes (whiteout) is still shipped with the image and is
still found, with the layer that added it and the one that deleted it.
All platforms of a multi-arch image are scanned by default: an amd64 CI
runner would otherwise miss malware in the arm64 variant.
No Docker socket: images are pulled straight from the registry.
Scanning is done by ClamAV's clamd over its socket protocol. meles does not
link against libclamav and stays Apache-2.0 licensed.
Besides ClamAV's signatures, the Helm chart ships about 140 curated YARA
rules for cryptominers, Linux malware, webshells and attacks on
containers, run by clamd as well.
By default meles only reports, and it never deletes anything. It is no
substitute for image signing, SBOMs or runtime detection.
Documentation
docs/getting-started.md: a step-by-step tour,
from a first scan to the scan gate in a cluster
docs/results.md: what Clean, Infected, Incomplete and
Error mean, what Clean does not guarantee, limits and false positives
docs/popular-images.md: results of scanning 47
popular images and 14 known malicious images
this README: using meles (CLI, web UI, Kubernetes, Harbor)
docs/architecture.md: how it works, where state
lives, security model, design decisions
Each release comes with
binaries for Linux and macOS (amd64, arm64), a multi-arch image and the Helm
chart:
VERSION=0.3.3
# Binary
curl -fsSLO https://github.com/movray/meles/releases/download/v$VERSION/meles_${VERSION}_linux_amd64.tar.gz
tar -xzf meles_${VERSION}_linux_amd64.tar.gz meles
# Image (linux/amd64, linux/arm64; no shell, runs as non-root)
docker run --rm ghcr.io/movray/meles:$VERSION version
# Helm chart (see Kubernetes below)
helm install meles oci://ghcr.io/movray/charts/meles --version $VERSION -n meles -f my-values.yaml
# From source
go install github.com/movray/meles/cmd/meles@v$VERSION
Binaries, image and chart are built by the
release workflow and carry signed build
provenance. The image is scanned with meles and Trivy before it is published.
Check the provenance with the GitHub CLI:
Image and chart are also signed with cosign (keyless), so admission
policies such as Kyverno or the Sigstore policy-controller can check them.
The signatures are Sigstore bundles stored as OCI referrers: verify with
cosign 3 (cosign 2 needs --new-bundle-format):
You need a running clamd. With apt install clamav-daemon meles finds its
socket (/run/clamav/clamd.ctl) on its own; the clamav/clamav image works,
too (see TL;DR; loading the signatures takes a minute or two).
meles selftest # checks the whole chain with EICAR test images
# (--yara: also the default YARA rules, if loaded)
meles image alpine:3.20
meles image --format json --platform linux/amd64 ghcr.io/org/app:1.2
clean (or findings with --exit-code 0, report-only mode)
1
malware found, or files were not scanned (change with --exit-code and --skipped-exit-code)
2
error: pull, engine or configuration. Never reported as clean.
meles fails the pipeline on findings by default, so it works as a gate
without extra flags.
Files that were not scanned (above --max-file-size, or above one of clamd's
limits) are listed as skipped, and the report is marked incomplete: the table
says "Scan INCOMPLETE" instead of "No malware found.", the JSON report has
"complete": false, and meles exits with 1 like on a finding. Any size
limit can be dodged by making a file larger than it, so an unscanned file
must not pass a security gate. Use --skipped-exit-code 0 to only report
skipped files, or 2 to treat them as an error.
--max-file-size defaults to 768M and can be raised up to ClamAV's own
limit of 2047M. Files above 4 MiB are streamed to clamd, so a high limit
costs no memory in meles; clamd keeps each stream in a temporary file while
it scans it. clamd's StreamMaxLength, MaxFileSize and MaxScanSize must
be at least as large (the Helm chart sets them to at least
scan.maxFileSize, see Limits in clamd;
clamd's own default StreamMaxLength is only 100M). Files that clamd
refuses as too large are reported as skipped. Larger files, such as big ML
models, cannot be scanned by ClamAV at all.
Configuration
Every flag can also be set as an environment variable MELES_<FLAG>, e.g.
MELES_CLAMD=tcp://clamd:3310 or MELES_PLATFORM=host. Flags win over
environment variables, which win over defaults.
Flag
Default
--clamd
unix:///run/clamav/clamd.ctl
unix:///path, tcp://host:3310 or tls://host:3310 (clamd-proxy)
--clamd-token
token for meles clamd-proxy; set it as MELES_CLAMD_TOKEN, a flag shows up in the process list
--clamd-ca
system roots
CA certificate of meles clamd-proxy
--clamd-timeout
5m
wait for clamd's verdict on a file; keep it above clamd's MaxScanTime
--platform
all
all, host or a list like linux/amd64,linux/arm64
--format
table
table, json, sarif (SARIF 2.1.0, e.g. for GitHub code scanning)
--exit-code
1
exit code on findings; 2 is reserved for errors
--skipped-exit-code
1
exit code when files were not scanned; 0 = report only
--max-file-size
768M
larger files are skipped and reported; at most 2047M, keep ≤ clamd's StreamMaxLength
--max-layer-size
4G
hard limit per layer (uncompressed); exceeding it is an error
--max-files
500000
hard limit of entries per layer
--concurrency
4
parallel clamd sessions
--ignorefile
YAML file with ignore rules, see below
--input
read the image from a local OCI layout or docker save archive instead of a registry, see below
--registry-mirror
pull a registry's images from a mirror first, e.g. docker.io=harbor.example.com/dockerhub; repeatable
Registry credentials come from the Docker config (~/.docker/config.json or
$DOCKER_CONFIG).
--registry-mirror registry=host[/path] pulls images of registry from
host/path/<repository> first, e.g. from a Harbor proxy cache project:
docker.io=harbor.example.com/dockerhub pulls nginx:1.27 as
harbor.example.com/dockerhub/library/nginx:1.27. The registry itself is
the fallback when the mirror fails, as in containerd, and reports keep the
original reference. A mirror is trusted for tags; for digests meles checks
that the mirror serves exactly that digest. Registries that are only other
names for Docker Hub (such as cr.smallstep.com) need their own entry.
Ignore rules
False positives (a miner detector's test data, a network tool) and files
the engine cannot scan for a known harmless reason would otherwise turn a
pipeline red for good. An ignore file lists them, each with a reason and an
expiry date at most a year ahead:
# meles-ignore.yaml
rules:
- name: php-phar-test-quine
# Every php:* image ships the PHP sources. ext/phar/tests/bug81726.gz
# unpacks to itself, so clamd stops at MaxRecursion whatever the limit.
path: /usr/src/php.tar.xz
signature: Heuristics.Limits.Exceeded.MaxRecursion
reason: PHP test file bug81726.gz is a gzip that contains itself
expires: "2027-06-30"
- name: monitor-miner-samples
signature: "*.Coinminer.*"
image: ghcr.io/acme/monitor
path: /opt/monitor/testdata/**
reason: detection samples of our miner monitor, reviewed 2026-10
expires: "2027-01-31"
A rule matches when all of its set fields match; it needs at least one of
path, signature and sha256. path and signature are globs (* and
? within a path segment, ** across segments), image is a repository
glob or an image digest sha256:…, sha256 names exactly one file content
(the JSON output has the hash of every finding and skipped file). Skipped
files have signatures too: clamd's Heuristics.Limits.Exceeded.*, or
meles.Limits.MaxFileSize, meles.Limits.StreamMaxLength and
meles.Unsupported.TarEntry.
Ignored entries stay in the report, marked with the rule and its reason;
they only no longer count for the verdict and the exit code. Once a rule has
expired, the entry counts again and the report says so. An invalid rule
(no reason, no date, a date more than a year ahead, an unknown field) fails
the run. Scan errors can never be ignored.
Local images
--input scans an image that is not in a registry yet, so that a pipeline
can check it before pushing it:
meles reads OCI image layouts (a directory or a tar of one, as written by
docker save since Docker 25, buildx type=oci, podman save --format oci-archive, skopeo oci-archive:) and the docker save format of older
Docker versions and of plain podman save. Tars may be gzip or zstd
compressed; a compressed tar is unpacked into one temporary file first
(TMPDIR), an uncompressed one is read in place. If the input holds several
images, name the one to scan: meles image --input all.tar app:1.4. The
report names the image as the archive does; for an archive without names
(e.g. crane pull --format=oci), the name you give is used, so that ignore
rules with image: match. Layer contents are checked against their digests
while they are read, as for a registry.
CI
meles needs a clamd to talk to. In CI there are two ways to get one: start
it in the job, or use the clamd of a cluster that runs the Helm chart. meles itself comes
as a release binary, with go install or as the image ghcr.io/movray/meles
(see Install).
A clamd in the job (GitHub Actions). The official ClamAV image downloads
the signature database from Cisco Talos. Keep it in the Actions cache, so
that each run fetches only the small daily update and stays within their
rate limits. clamd needs about 1.5 GB of memory and a minute to load the
database.
jobs:
malware-scan:
runs-on: ubuntu-latest
env:
MELES_CLAMD: tcp://127.0.0.1:3310
IMAGE: ghcr.io/org/app:${{ github.sha }}
steps:
- name: Install meles
run: |
v=0.3.3
curl -fsSL "https://github.com/movray/meles/releases/download/v$v/meles_${v}_linux_amd64.tar.gz" \
| sudo tar -xz -C /usr/local/bin meles
- name: Signature database from the cache
uses: actions/cache@v4
with:
path: clamav-db
key: clamav-db-${{ github.run_id }}
restore-keys: clamav-db-
- name: Start clamd
run: |
mkdir -p clamav-db && chmod 0777 clamav-db
docker run --rm -v "$PWD/clamav-db:/var/lib/clamav" --entrypoint freshclam \
clamav/clamav:1.4 --foreground --stdout
docker run -d --name clamd -p 127.0.0.1:3310:3310 -e CLAMAV_NO_FRESHCLAMD=true \
-v "$PWD/clamav-db:/var/lib/clamav" clamav/clamav:1.4
for i in $(seq 120); do
(exec 3<>/dev/tcp/127.0.0.1/3310 && printf 'zPING\0' >&3 && head -c4 <&3 | grep -q PONG) 2>/dev/null && exit 0
sleep 2
done
docker logs clamd; exit 1
# Optional: check meles and clamd with EICAR test images first, so that
# a broken setup is not mistaken for a finding.
- run: meles selftest
- run: meles image "$IMAGE"
The official image has no YARA rules; meles selftest --yara and the
curated rules need the clamd of the Helm chart (or the rules from
charts/meles/rules in the database directory).
The clamd of a cluster. CI runners in the cluster (for example
self-hosted runners) can use the chart's clamd through its clamd-proxy:
allow their namespace with networkPolicy.clamdExtraFrom and store the
token and the CA (see clamd authentication) as CI
secrets. No signature download, and the chart's YARA rules are included.
In SARIF, findings are errors and skipped files warnings (the scan is
incomplete). Entries an ignore rule takes out of the verdict are kept as
suppressed results with the rule's reason. The location is the path in the
image; image, platform, layer and Dockerfile instruction are in the result's
properties. The fingerprint leaves out the digest, so an alert stays the
same alert in the next version of the image. A failed scan marks the run
unsuccessful instead of producing an empty, clean-looking report.
GitLab CI. The ClamAV image as a service. It downloads the database on
every run, so keep the number of runs moderate or use the clamd of a
cluster. The job waits until clamd has loaded the database. The meles image
has no shell, so the job installs meles into a Go image:
malware-scan:
image: golang:1.26
services:
- name: clamav/clamav:1.4
alias: clamd
variables:
MELES_CLAMD: tcp://clamd:3310
script:
- go install github.com/movray/meles/cmd/meles@main
- for i in $(seq 30); do meles selftest > /dev/null 2>&1 && break; sleep 10; done
- meles selftest
- meles image "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
Web UI
meles server serves a web UI and JSON API:
Dashboard – quick scan, images that need attention, upcoming and recent runs
Scans – image references with an optional cron schedule (@daily,
0 3 * * 1-5, @every 6h, CRON_TZ=Europe/Berlin …)
Runs – every run with its result; the run page shows each finding with
path, signature, platform, layer, Dockerfile instruction and whether a later
layer deleted it
Reports – runs per day, image status, top signatures, CSV export
make run-server # http://127.0.0.1:8080, database in meles.db
The button in the header refreshes the page, and the list next to it sets an
interval; the browser remembers it. Auto refreshes only while a run is
active. The UI follows the system's light or dark mode; the switch in the header
overrides it for the browser (stored in its local storage).
Runs and reports are stored in SQLite. The server has no login of its own:
keep it internal or put an authenticating proxy in front of it.
meles server --ignorefile meles-ignore.yaml applies ignore rules (format
below) to its runs; the file is read at every run. A run keeps the verdict
of its time: a new rule applies from the next run on.
To try it with infected test images locally, see
development.md.
API: GET/POST /api/scans, GET/PUT/DELETE /api/scans/{id},
POST /api/scans/{id}/run, GET/POST /api/runs, GET /api/runs/{id},
GET /api/runs/{id}/report, GET /api/selftest, /healthz, /readyz (clamd
reachable; a failed selftest does not make the server unready, the UI has to
show it).
Kubernetes
The Helm chart in charts/meles installs these roles:
Component
Purpose
<release>-mirror
cvdupdate + nginx. The only component that downloads signatures from Cisco Talos (at most hourly); also serves the YARA rules.
<release>-clamd
clamd workers; get signatures from the mirror via freshclam PrivateMirror.
<release>-server
web UI, scheduler, run history (SQLite on a PVC).
<release>-operator
scans the image of every pod in the cluster, writes MalwareReports (off by default, see below).
Plus a CronJob <release>-selftest that checks the chain daily (with
yara.defaultRules also that clamd has loaded the YARA rules). The server
runs the same check every 6 hours and shows the result in the UI.
Each role can be turned off; with clamd.enabled=false set clamd.address
to an existing clamd.
The clamd image starts as root and drops privileges itself, so the namespace
needs the baseline Pod Security level, not restricted.
Important values (see charts/meles/values.yaml):
Value
Default
imagePullSecrets
[]
pull secrets for the meles image
scan.maxFileSize
768M
--max-file-size of meles and clamd's StreamMaxLength (MaxScanSize/MaxFileSize at least this); at most 2047M
scan.maxLayerSize
4G
--max-layer-size of meles: hard limit per layer (uncompressed); machine learning images can need more
clamd.maxScanSize
2047M
clamd's MaxScanSize and MaxFileSize: data scanned per file including unpacked content; at least scan.maxFileSize
clamd.maxScanTime
600000
clamd's MaxScanTime in milliseconds; larger compressed archives may need more. --clamd-timeout of the meles clients follows it (plus a minute, at least 5 minutes)
own YARA rules from ConfigMaps, e.g. [{configMap: team-rules, files: [team.yar]}]
server.timezone
UTC
time zone of cron schedules
server.clusterReports.enabled
with operator.enabled
page "Cluster" with the operator's MalwareReports (ClusterRole: read malwarereports)
server.clusterReports.rescan
true
"Rescan" button in the UI (adds patch on malwarereports)
server.clusterReports.ignore
false
"Ignore…" button and page "Ignore rules" (adds create/delete on malwareignores and clustermalwareignores), see below
server.clusterReports.historyDays
365
keep the history of the reports this many days
server.registryAuthSecret
""
kubernetes.io/dockerconfigjson secret for private images to scan
scan.registryMirrors
[]
mirrors the server and the operator pull from first, e.g. docker.io=harbor.example.com/dockerhub (see --registry-mirror)
scan.registryCA.configMap
""
ConfigMap with an additional CA (key, default ca.crt) for registries and mirrors, e.g. a private CA of Harbor
scan.allowPrivateRegistries
[]
registries on private addresses the server and the operator may pull from: host, host:port, *.domain or a network such as 10.0.0.0/8 (see --allow-private-registry); mirror hosts are allowed, loopback and link-local never
server.httpRoute.*, server.ingress.*
off
expose the UI (Gateway API or Ingress); needs server.oauth2Proxy or server.allowUnauthenticated
server.allowUnauthenticated
false
allow server.httpRoute or server.ingress without server.oauth2Proxy
clamd only for pods of the release, the mirror only for clamd
networkPolicy.clamdExtraFrom
[]
further clients of clamd, e.g. CI runners in other namespaces
networkPolicy.serverFrom
[]
restrict access to the UI, e.g. to the ingress controller
operator.enabled
false
run the operator
operator.platform
nodes
nodes (architectures of the cluster's nodes), all, or a list
operator.retryAfter
1h
retry of failed scans
operator.retryIncompleteAfter
12h
rescan of images with skipped files
operator.pullSecrets.clusterWide
false
read the pods' imagePullSecrets in all namespaces; otherwise per namespace with a RoleBinding (see below)
operator.registryAuthSecret
""
kubernetes.io/dockerconfigjson secret the operator always uses, e.g. a Docker Hub account
operator.pruneInterval
30m
delete reports of ReplicaSets, StatefulSets and DaemonSets without pods; 0 disables
operator.rescanInterval
24h
rescan after a signature update at most this often; 0 disables
operator.serviceMonitor.enabled
false
ServiceMonitor for the operator's /metrics (labels, interval)
operator.prometheusRule.enabled
false
alerts as a PrometheusRule (labels, alertLabels, disabled, errorFor, gateHeldFor, uiURL)
operator.grafanaDashboard.enabled
false
Grafana dashboard as a ConfigMap for the sidecar (labels, default grafana_dashboard: "1"; namespace, annotations)
networkPolicy.operatorMetricsFrom
[]
further peers allowed to reach the operator's /metrics and /status, e.g. Prometheus
operator.gate.enabled
false
scan gate: hold new pods in labelled namespaces until their images are scanned (see below)
operator.gate.failOpen
true
release held pods when the scan failed in clamd
operator.gate.failurePolicy
Ignore
webhook failure policy; Fail blocks pod creation in gated namespaces while the operator is down
operator.gate.tls.certManager.*
off
webhook certificate from cert-manager instead of a self-signed one
YARA rules
charts/meles/rules/meles.yar holds about 140 YARA rules from open sources
(signature-base, Volexity, ditekSHen, SEKOIA and others), selected for
containers: cryptominers, Linux malware, webshells and attacks on Docker
and Kubernetes. meles-own.yar adds rules written for meles. They were
checked against the images of a typical cluster without a false positive. The mirror serves them, freshclam loads them into
every clamd pod, and clamd runs them with ClamAV's YARA support; findings
look like YARA.SIGNATURE_BASE_XMRIG_Monero_Miner.UNOFFICIAL.
Every finding of such a rule names the rule's author, license and source
(CLI, JSON, MalwareReports, web UI, Harbor): the Detection Rule License of
some sources requires it. Sources and licenses:
charts/meles/rules/README.md.
Own rules go into ConfigMaps of the release namespace and yara.extra; the
mirror serves them next to the default ones. ClamAV supports a subset of
YARA (no modules, no global rules) and skips other rules silently, so
check them first: clamscan -d team.yar /dev/null must report as many
"Known viruses" as the file has rules.
Changed rules reach clamd with freshclam's next check
(clamd.freshclam.checksPerDay, default hourly). The clamd-proxy appends a
hash of the loaded rules to the signature version (28164+rules.3f2a…), so
the operator and the layer caches rescan as after a signature update.
Without clamd.auth (no proxy) new rules do not trigger rescans.
With the CLI against your own clamd, put meles.yar and meles-own.yar into
clamd's database directory and reload clamd.
Operator
With operator.enabled=true, meles watches all pods of the cluster and scans
the image every container (including init containers) runs, by digest. The
result is a MalwareReport (meles.io/v1alpha1) in the pod's namespace, one
per workload and container, owned by the workload and deleted with it:
A workload is the pod's controller (ReplicaSet, StatefulSet, DaemonSet,
Job, or a custom resource such as a CloudNativePG Cluster), the CronJob
of a Job, or the pod itself.
Every digest is scanned once; other workloads with the same image get a
copy of the result.
Status is Clean, Infected, Incomplete (files skipped) or Error
(not scanned, e.g. a private registry or an image imported into the node).
Error and Incomplete are never clean.
If clamd fails, a scan is tried again for almost 4 minutes before it ends
as Error, so a clamd that is starting or being replaced does not show up
in the reports. Such an Error is then retried after at most 5 minutes.
Any other Error is retried after operator.retryAfter (1h), Incomplete
after operator.retryIncompleteAfter (12h), for example once clamd's limits
(clamd.maxScanSize, clamd.maxScanTime) were raised. Other results are
rescanned when
the signature database changed, at most once per operator.rescanInterval
(24h; each rescan pulls the image again).
Reports of ReplicaSets, StatefulSets and DaemonSets without pods, such as
the old ReplicaSets a Deployment keeps for rollbacks, are deleted every
operator.pruneInterval. A CronJob keeps its report between runs.
A deleted report is written again right away. To rescan an image now,
e.g. after raising clamd's limits, annotate one of its reports; all
reports of the image get the new result:
Images of private registries are pulled with the imagePullSecrets of the
pods that run them and of their service accounts, as the kubelet does,
where the operator may read them. That is opt-in per namespace: the team
that owns it binds the ClusterRole <release>-pull-secret-reader (get
on secrets and serviceaccounts, no list or watch) to the
operator, and nobody has to give it every secret of the cluster:
A team that wants to expose only its pull secret writes its own Role with
resourceNames. Until then, private images are reported as Error,
never as Clean, and the error names the command for its namespace.
operator.pullSecrets.clusterWide binds the role in all namespaces
instead. operator.registryAuthSecret adds one Docker config the
operator always uses, e.g. a Docker Hub account against its pull rate
limit or a registry mirror, without any permission on other secrets.
Credentials that exist only on the nodes (kubelet credential providers)
are not covered. Mirrors configured on the nodes (containerd,
registries.yaml of k3s) are not seen either: set the same ones in
scan.registryMirrors, or the operator pulls from the upstream registry
and spends its pull rate limit, e.g. Docker Hub's for anonymous pulls,
which it shares with the kubelet (see
Registry rate limits and a pull-through cache).
Ignore rules (see Ignore rules) live in two resources:
MalwareIgnore for the reports of its namespace, so that teams manage the
exceptions for their own workloads, and the cluster-scoped
ClusterMalwareIgnore for administrators. Who may create them is up to
Kubernetes RBAC. Changed rules apply to the reports right away, without a
rescan; ignored entries stay in the report, marked with the rule
(<object>#<n> or <object>/<name>), and the summary counts them as
ignored. Invalid and expired rules are listed in the object's status:
$ kubectl get clustermalwareignores
NAME RULES PROBLEMS AGE
known-harmless 1 2m
With server.clusterReports.ignore=true rules can also be created in the
web UI: the button Ignore… at a finding or skipped file opens a form
prefilled with path, signature, image and the file's sha256. Reason and
expiry (default 90 days, at most a year) are required, and the rule applies
either to the report's namespace (a MalwareIgnore) or to the whole
cluster (a ClusterMalwareIgnore). Every rule becomes an object of its own,
labelled app.kubernetes.io/managed-by: meles-server, with the user from
oauth2-proxy (X-Forwarded-Email) in the annotation meles.io/created-by.
The page Ignore rules lists all rules with their origin: created in the
UI (by whom), or applied by Argo CD, Flux, Helm, or kubectl/Git. The UI
deletes only the rules it created. The server's own runs apply the
ClusterMalwareIgnores too.
This is off by default: everyone who can open the UI could then take
findings out of the verdict and, with the scan gate on, let an image run.
Limit who may log in first (server.oauth2Proxy.allowedGroups).
The web UI shows the reports on the page Cluster (filter by result,
namespace or image; details with findings and skipped files; a "Rescan"
button) and as JSON under /api/cluster/reports. The server reads them
from the Kubernetes API, the reports stay the only source. Every change of a
report (a new result, a deletion) is also recorded in the server's database:
the report page shows the history of the workload, across rollouts for the
ReplicaSets of a Deployment, and the Cluster page since when each status
holds (JSON: /api/cluster/reports/<namespace>/<name>/history). Everyone who
can open the UI sees the reports of all namespaces.
Above the reports, the Cluster page shows what the operator does: scans
running and waiting (by priority), the oldest waiting scan, recent scans
with errors, and the pods the scan gate holds (JSON:
/api/cluster/operator). The operator serves this at /status and
Prometheus metrics at /metrics on port 8080, behind the headless service
<release>-operator-metrics:
operator.serviceMonitor.enabled creates a ServiceMonitor (with
honorLabels, so namespace of meles_operator_reports stays the
report's); with network policies on, allow Prometheus in
networkPolicy.operatorMetricsFrom. operator.grafanaDashboard.enabled
adds a Grafana dashboard (reports, queue, scans, scan gate) as a ConfigMap
for Grafana's dashboard sidecar, as in kube-prometheus-stack; the JSON is
in charts/meles/dashboards/ for importing it by hand.
operator.prometheusRule.enabled adds alerts as a PrometheusRule:
Alert
Severity
When
MelesInfectedWorkload
critical
a workload's container runs an Infected image; one alert each, naming workload, container and image
MelesScanErrors
warning
reports stay Error for errorFor (6h): images not scanned
MelesScansIncomplete
info
reports stay Incomplete for errorFor: files skipped
MelesOperatorDown
warning, critical with the scan gate
no operator replica reachable for 10 minutes
MelesOperatorNoLeader
warning
no replica holds the leader lease for 10 minutes
MelesScanQueueStuck
warning
scans queued, none finished for 30 minutes
MelesGatePodsHeld
warning
the scan gate holds pods for gateHeldFor (30m)
MelesGateReleasedUnscanned
warning
the scan gate released pods without a complete scan
Each alert carries a url annotation into the web UI (the report, or the
Cluster page filtered by namespace and status), from server.ingress,
server.httpRoute or operator.prometheusRule.uiURL. The gate's alerts
exist only with operator.gate.enabled; leave out others
with operator.prometheusRule.disabled, e.g. {MelesScansIncomplete: true}.
The CRD is in charts/meles/crds/. Helm installs it with the chart but never
updates or deletes it; after an upgrade apply it again:
kubectl apply -f charts/meles/crds/
Scan gate
By default meles only reports: a pod runs while its image is scanned, and
the operator has no permission to change pods. With operator.gate.enabled
an administrator holds new pods until their images are scanned, per
namespace:
kubectl label namespace shop meles.io/gate=enforce # or audit
Mode
Released when
enforce
every image is Clean (ignored findings do not count)
audit
no image is Infected
A held pod is SchedulingGated; kubectl describe pod shows why in an
event (ScanGateHeld), and its MalwareReport has the details. Once
released, the pod runs exactly the scanned image: the operator pins it to
the digest (busybox:1.37@sha256:…). Infected images never start, and a
rollout of an infected version leaves the old pods running. An image that
was scanned before is released at once; rescans never hold a pod.
A workload opts out with the annotation meles.io/gate: skip on its pod
template, where an administrator allows it:
kubectl label namespace shop meles.io/gate-skip=allowed.
Members of a gated namespace cannot bypass the gate: a
ValidatingAdmissionPolicy (operator.gate.protect, on with the gate)
refuses meles.io/gate: skip without that label, spec.nodeName on new
pods, removing the scheduling gate, meles.io/gate-mode: audit outside
audit namespaces and changing the image of a pod; only the operator may
do the last three. It runs in the API server and blocks nothing more
while meles is down. To see first what it would refuse:
operator.gate.protect.validationActions: [Warn] (or [Audit]).
kube-system, the release namespace and operator.gate.excludeNamespaces
are never gated. Pods that exist already are not affected.
If clamd fails, held pods are released with a warning event
(ScanGateReleasedUnscanned) unless operator.gate.failOpen=false.
Images that cannot be pulled or resolved stay held in enforce mode.
If the operator is down, new pods start ungated
(operator.gate.failurePolicy: Ignore); Fail refuses to create pods in
gated namespaces until it is back. The chart runs two operator replicas
while the gate is on, so that a rollout of the operator does not open the
gate.
With the gate the operator may patch pods and create events in all
namespaces. Kubernetes 1.30 or later is required.
How it works and why it uses a webhook rather than a
MutatingAdmissionPolicy: architecture.md.
Harbor
With harborAdapter.enabled=true, meles runs as a
pluggable scanner for
Harbor (meles harbor-adapter): Harbor sends every pushed image to meles
and shows the result, before the image runs anywhere. Register it under
Administration → Interrogation Services:
Authorization: Bearer, token from
kubectl -n <namespace> get secret <release>-harbor-adapter-token -o jsonpath='{.data.token}' | base64 -d
Harbor knows vulnerability and SBOM reports only, so meles reports a finding
as an entry of severity Critical (the signature as ID, the file path as
package; layer, status and sha256 under vendor_attributes) and a file that
was not scanned as an entry of harborAdapter.skippedSeverity (Critical by
default). With the project setting Prevent vulnerable images from running
at Critical, Harbor refuses to hand out infected images.
A Harbor project uses one scanner. To keep the CVE scan, chain Harbor's
Trivy adapter with harborAdapter.upstream.url (e.g.
http://harbor-trivy.harbor:8080): every scan goes to both, the report
contains the CVEs and the malware findings, and SBOM requests are passed
through. Ignore rules go into harborAdapter.ignoreRules; Harbor's CVE
allowlist works on the signature IDs as well.
Registry rate limits and a pull-through cache
The operator pulls the manifests and layers of every image it scans, and
again for each rescan, independently of the kubelet: a second pull per
image. meles does not throttle these pulls on its own, since that would only
delay the scans. Without credentials it pulls from the same address
as the nodes, so both share the registry's limit for anonymous pulls
(Docker Hub: 100 per hour per IP address); a cluster with many Docker Hub
images runs into TOOMANYREQUESTS, in the operator's reports and in the
kubelet's image pulls. Credentials in operator.registryAuthSecret raise
the limit for meles only. A pull-through cache helps both: every image is
fetched from Docker Hub once, and later pulls come from the cache.
With Harbor:
Administration → Registries: a new endpoint of provider Docker
Hub, anonymous or with an access token (read-only) for a higher limit.
Projects: a new project, e.g. dockerhub, with Proxy Cache on that
endpoint. Harbor deletes cached images that were not pulled for 7 days
(the project's retention rule); the space is freed only by a garbage
collection, so give it a schedule under Administration → Clean Up.
meles:
scan:
registryMirrors:
- docker.io=harbor.example.com/dockerhub
# Registries that are only other names for Docker Hub need their own entry.
- cr.smallstep.com=harbor.example.com/dockerhub
registryCA:
configMap: my-root-ca # only if Harbor's certificate is from a private CA
Nodes: the container runtime needs the same mirrors, e.g. in
/etc/rancher/k3s/registries.yaml on every k3s node (restart k3s or
k3s-agent afterwards; running pods keep running), or in containerd's
hosts.toml elsewhere:
meles and containerd both fall back to the registry itself when the mirror
fails, so an outage of Harbor costs time, not pulls; Harbor's own images
usually come from Docker Hub as well. meles trusts the mirror for tags and
checks digests (see --registry-mirror), and reports keep the original
image reference.
Login for the web UI
meles has no login of its own. Without one, anyone who reaches the UI can
create and start scans and read all reports. The chart can run
oauth2-proxy as a sidecar
in front of the UI: only users logged in with your OIDC provider (Keycloak,
GitHub, Entra ID, ...) get through, optionally only members of certain
groups. The server then listens on 127.0.0.1, so the login cannot be bypassed
from inside the cluster either.
Create an OIDC client (confidential, standard flow) with the redirect URI
https://<ui-host>/oauth2/callback. For allowedGroups the ID token needs
a groups claim (Keycloak: group membership mapper).
Store its secret: kubectl -n meles create secret generic meles-oidc --from-literal=client-secret=...
Set the values:
server:
oauth2Proxy:
enabled: true
issuerUrl: https://keycloak.example.com/realms/main
clientId: meles
existingSecret: meles-oidc
allowedGroups: [meles-admins]
# If the provider's certificate comes from an internal CA: a ConfigMap
# with the CA certificate in the release namespace.
providerCA: {configMap: internal-ca, key: ca.crt}
# Or httpRoute (Gateway API) with parentRefs and hostnames.
ingress:
enabled: true
className: nginx
host: meles.example.com
tls: [{secretName: meles-tls, hosts: [meles.example.com]}]
oauth2-proxy only accepts users with a verified e-mail address.
Without oauth2-proxy keep the UI internal (port-forward) or put another
authenticating proxy in front of it. The chart refuses server.ingress and
server.httpRoute without oauth2-proxy; if another proxy handles the login,
or the UI stays on an internal network, set server.allowUnauthenticated=true.
clamd authentication
clamd has no authentication, and any client could send SHUTDOWN or
SCAN <path>. With clamd.auth.enabled (default) clamd listens only on
127.0.0.1 in its pod; the sidecar meles clamd-proxy accepts clients over
TLS with a token and forwards only PING, VERSION, IDSESSION, INSTREAM
and END. Server and selftest of the release are configured automatically.
Other clients, e.g. CI jobs in another namespace (also allow them with
networkPolicy.clamdExtraFrom):
The token secret may hold several tokens, one per line: add the new one,
switch the clients, remove the old one. The proxy reloads the token file and
the certificate when they change.
The PVCs of mirror and server are kept on helm uninstall
(helm.sh/resource-policy: keep): the databases count against the Cisco
Talos rate limits, the server holds the run history.
clamd needs about 1.5 GB of memory with the full database and briefly almost
twice that during a reload.
Apache-2.0. The clamav/clamav image used for the workers contains ClamAV,
which is licensed under GPLv2. The YARA rules in charts/meles/rules keep
the licenses of their sources (Detection Rule License 1.1, BSD-2-Clause,
Apache-2.0), see the README there.
Command testregistry serves the meles test images (EICAR, and a file the default YARA rules detect) on a fixed address, for trying the web UI locally and for the exit code checks in CI:
Command testregistry serves the meles test images (EICAR, and a file the default YARA rules detect) on a fixed address, for trying the web UI locally and for the exit code checks in CI:
Command yaraindex writes the index of the default YARA rules (charts/meles/rules/*.yar) that is embedded in meles: rule name → author, license and source.
Command yaraindex writes the index of the default YARA rules (charts/meles/rules/*.yar) that is embedded in meles: rule name → author, license and source.
Package harbor implements Harbor's pluggable scanner adapter API (spec v1.2, https://github.com/goharbor/pluggable-scanner-spec), so that Harbor scans every pushed image with meles.
Package harbor implements Harbor's pluggable scanner adapter API (spec v1.2, https://github.com/goharbor/pluggable-scanner-spec), so that Harbor scans every pushed image with meles.
Package ignore matches findings and skipped files against ignore rules: known false positives, or files the engine cannot scan completely for a known harmless reason.
Package ignore matches findings and skipped files against ignore rules: known false positives, or files the engine cannot scan completely for a known harmless reason.
Package scan scans container images layer by layer: it pulls an image, streams every file of every layer to a scan engine and works out which findings are visible in the final filesystem and which were deleted by a later layer but are still shipped with the image.
Package scan scans container images layer by layer: it pulls an image, streams every file of every layer to a scan engine and works out which findings are visible in the final filesystem and which were deleted by a later layer but are still shipped with the image.
Package selftest checks the whole scan chain: it serves images with EICAR test files from an in-memory registry and compares what the scanner finds with what it must find.
Package selftest checks the whole scan chain: it serves images with EICAR test files from an in-memory registry and compares what the scanner finds with what it must find.
Package server is the meles web UI and JSON API: configured scans with schedules, scan runs with their results, reports, and the MalwareReports of the meles operator.
Package server is the meles web UI and JSON API: configured scans with schedules, scan runs with their results, reports, and the MalwareReports of the meles operator.
Package store keeps configured scans, scan runs and their findings, and the history of the cluster's MalwareReports in SQLite (pure Go driver, no CGO).
Package store keeps configured scans, scan runs and their findings, and the history of the cluster's MalwareReports in SQLite (pure Go driver, no CGO).