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.
This commit is contained in:
@@ -58,6 +58,29 @@ gradle :app:installDebug
|
||||
adb shell am start -n net.awan.pipelines/.MainActivity
|
||||
```
|
||||
|
||||
### Capturing screenshots
|
||||
|
||||
Never write `adb … screencap` to a file through `exec-out` or a redirect: on a
|
||||
device with more than one display (e.g. the fold emulator's inner and cover
|
||||
panels) `screencap` prints a `[Warning] Multiple displays were found…` line to
|
||||
stderr, adb folds it into the stream, and the `.png` ends up 100+ KB of text
|
||||
while `adb` still exits 0. Such a file must never be cited as evidence. Capture
|
||||
on the device to a file, pull it, name the display explicitly, and validate the
|
||||
bytes before use:
|
||||
|
||||
```sh
|
||||
android/scripts/capture_png.sh -s <serial> <out.png> # capture + validate
|
||||
android/scripts/capture_png.sh --check <file.png> # validate an existing file
|
||||
```
|
||||
|
||||
The helper resolves the primary SurfaceFlinger display id (`dumpsys
|
||||
SurfaceFlinger --display-id`, the id `screencap -d` expects - not the logical
|
||||
`dumpsys display` id), captures `-d <id>` to `/sdcard`, pulls, and checks the
|
||||
PNG magic bytes (and the reported type). A file that is not a real image is
|
||||
deleted and the helper exits non-zero, so a bad capture stops the run with
|
||||
`blocked` instead of reaching an approval. Every UI-capturing run must use this
|
||||
helper and state in its evidence that each image was validated.
|
||||
|
||||
## Configuration
|
||||
|
||||
Open the **Settings** tab and enter:
|
||||
|
||||
Executable
+179
@@ -0,0 +1,179 @@
|
||||
#!/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
|
||||
Reference in New Issue
Block a user