Files
pipelines/android/scripts/capture_png.sh
T
alan 66d4856348 Validate Android screenshot captures before use
Add android/scripts/capture_png.sh, which captures on-device (screencap -p -d <SurfaceFlinger id>) to /sdcard, pulls the file, and validates PNG magic bytes plus the reported type, deleting and failing on anything that is not a real image. Document the multi-display warning failure mode and the required helper in android/README.md so every UI-capturing run captures and validates instead of writing adb screencap straight to a file.
2026-10-16 01:22:45 +01:00

180 lines
5.9 KiB
Bash
Executable File

#!/usr/bin/env bash
# capture_png.sh - capture a validated PNG screenshot from an Android device.
#
# Why this exists: `adb ... screencap` written straight to a file (through
# `exec-out` or a stdout redirect) is not trustworthy. On a device with more
# than one display - e.g. the fold emulator, which exposes the inner and cover
# panels - screencap prints
#
# [Warning] Multiple displays were found, but no display id was specified!
#
# to stderr, adb folds that into the stream, and the ".png" becomes 100+ KB of
# text while adb still exits 0. A text file must never be cited as screenshot
# evidence. This helper captures on the device to a file, pulls it, names the
# display explicitly when more than one exists, and verifies the pulled bytes
# really are a PNG before returning success.
#
# Usage:
# capture_png.sh -s SERIAL OUT.png capture and validate; non-zero on any
# failure (and the bad file is removed)
# capture_png.sh --check FILE.png validate an existing file only
# capture_png.sh -h this help
#
# Set ADB to override the adb binary, otherwise PATH and the Android SDK
# locations are tried. Resolution of the display id uses the SurfaceFlinger
# ids that `screencap -d` actually expects, not the logical `dumpsys display`
# ids.
set -euo pipefail
PNG_MAGIC=89504e470d0a1a0a # \x89PNG\r\n\x1a\n
prog=$(basename "$0")
VALIDATE_REASON=""
die() { printf '%s: %s\n' "$prog" "$*" >&2; exit 1; }
usage() {
sed -n '3,20p' "$0" | sed 's/^# \{0,1\}//'
}
find_adb() {
if [ -n "${ADB:-}" ]; then
printf '%s\n' "$ADB"
return
fi
if command -v adb >/dev/null 2>&1; then
command -v adb
return
fi
local sdk
for sdk in "${ANDROID_HOME:-}" "${ANDROID_SDK_ROOT:-}" "$HOME/Library/Android/sdk"; do
if [ -n "$sdk" ] && [ -x "$sdk/platform-tools/adb" ]; then
printf '%s\n' "$sdk/platform-tools/adb"
return
fi
done
die "adb not found; set ADB or ANDROID_HOME"
}
# validate_png FILE - return 0 only for a real PNG; on failure set
# VALIDATE_REASON to a short explanation.
validate_png() {
local file=$1 magic
VALIDATE_REASON=""
magic=$(od -An -tx1 -N8 "$file" 2>/dev/null | tr -d ' \n')
if [ ! -s "$file" ]; then
VALIDATE_REASON="file is missing or empty"
return 1
fi
if [ "$magic" != "$PNG_MAGIC" ]; then
if head -c 9 "$file" | grep -q '^\[Warning\]'; then
VALIDATE_REASON="screencap warning text, not an image"
else
VALIDATE_REASON="magic bytes ${magic:-none} are not a PNG"
fi
return 1
fi
if command -v file >/dev/null 2>&1 && ! file -b "$file" | grep -q '^PNG image'; then
VALIDATE_REASON="reported type is '$(file -b "$file")', not a PNG image"
return 1
fi
return 0
}
# resolve_display_id ADB SERIAL - print the SurfaceFlinger id of the primary
# display (HWC display 0) so a multi-display device cannot emit the warning.
resolve_display_id() {
local adb=$1 serial=$2 ids primary
ids=$("$adb" -s "$serial" shell dumpsys SurfaceFlinger --display-id 2>/dev/null || true)
primary=$(printf '%s\n' "$ids" | sed -n 's/^Display \([0-9][0-9]*\) (HWC display 0):.*/\1/p' | head -1)
if [ -z "$primary" ]; then
primary=$(printf '%s\n' "$ids" | sed -n 's/^Display \([0-9][0-9]*\):.*/\1/p' | head -1)
fi
printf '%s\n' "$primary"
}
capture() {
local serial=$1 out=$2 adb primary remote rc count
[ -n "$serial" ] || die "-s SERIAL is required (never capture from an unspecified device)"
case $out in
*.png) ;;
*) die "output must end in .png: $out" ;;
esac
adb=$(find_adb)
primary=$(resolve_display_id "$adb" "$serial")
count=$("$adb" -s "$serial" shell dumpsys SurfaceFlinger --display-id 2>/dev/null | grep -c '^Display [0-9]' || true)
remote="/sdcard/.capture_png_$$_$(basename "$out")"
if [ -n "$primary" ]; then
rc=0
"$adb" -s "$serial" shell screencap -p -d "$primary" "$remote" || rc=$?
else
rc=0
"$adb" -s "$serial" shell screencap -p "$remote" || rc=$?
fi
if [ "$rc" -ne 0 ]; then
"$adb" -s "$serial" shell rm -f "$remote" >/dev/null 2>&1 || true
die "on-device screencap failed (exit $rc)"
fi
"$adb" -s "$serial" pull "$remote" "$out" >/dev/null || {
"$adb" -s "$serial" shell rm -f "$remote" >/dev/null 2>&1 || true
die "pull of $remote failed"
}
"$adb" -s "$serial" shell rm -f "$remote" >/dev/null 2>&1 || true
if ! validate_png "$out"; then
rm -f "$out"
die "$out is not a real image ($VALIDATE_REASON); deleted - refusing to use it as evidence"
fi
printf 'validated %s: PNG, %s bytes, %s display(s), display id %s; captured on device to file then pulled\n' \
"$out" "$(wc -c < "$out" | tr -d ' ')" "$count" "${primary:-default}"
}
check() {
local file=$1
[ -f "$file" ] || die "no such file: $file"
if validate_png "$file"; then
printf 'valid %s: PNG, %s bytes\n' "$file" "$(wc -c < "$file" | tr -d ' ')"
else
die "$file is not a real image ($VALIDATE_REASON); refusing to use it as evidence"
fi
}
serial=""
file=""
action=capture
while [ $# -gt 0 ]; do
case $1 in
-s)
serial=${2:-}
[ -n "$serial" ] || die "-s requires a serial"
shift 2
;;
--check)
action=check
file=${2:-}
[ -n "$file" ] || die "--check requires a file"
shift 2
;;
-h|--help)
usage
exit 0
;;
-*)
die "unknown option $1"
;;
*)
file=$1
shift
;;
esac
done
[ -n "$file" ] || die "no output file given (see -h)"
if [ "$action" = check ]; then
check "$file"
else
capture "$serial" "$file"
fi