From 570f8bdf67fa07dd4532b46929908bcbcd18f7ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Feb 2026 20:10:51 +0100 Subject: [PATCH] docs: harden agent-device skill security guidance --- skills/agent-device/SKILL.md | 11 ++++++++--- skills/agent-device/references/logs-and-debug.md | 16 ++++++++++++++++ skills/agent-device/references/permissions.md | 8 ++++++++ 3 files changed, 32 insertions(+), 3 deletions(-) diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md index 229fe0bd2b..96881c0f9a 100644 --- a/skills/agent-device/SKILL.md +++ b/skills/agent-device/SKILL.md @@ -108,6 +108,14 @@ agent-device batch --steps-file /tmp/batch-steps.json --json - iOS settings helpers are simulator-only; use faceid `match|nonmatch|enroll|unenroll`. - If using `--save-script`, prefer explicit path syntax (`--save-script=flow.ad` or `./flow.ad`). +## Security and Trust Notes + +- Prefer a preinstalled `agent-device` binary over on-demand package execution. +- If install is required, pin an exact version (for example: `npx --yes agent-device@ --help`). +- Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup. +- Logs/artifacts are written under `~/.agent-device`; replay scripts write to explicit paths you provide. +- Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs. + ## Common Mistakes - Mixing debug flow into normal runs (keep logs off unless debugging). @@ -115,9 +123,6 @@ agent-device batch --steps-file /tmp/batch-steps.json --json - Using URL opens with Android `--activity` (unsupported combination). - Treating `boot` as default first step instead of fallback. -If the CLI is not installed in environment, use: -`npx -y agent-device` - ## References - [references/snapshot-refs.md](references/snapshot-refs.md) diff --git a/skills/agent-device/references/logs-and-debug.md b/skills/agent-device/references/logs-and-debug.md index d2b7c0b3c7..febc941cc0 100644 --- a/skills/agent-device/references/logs-and-debug.md +++ b/skills/agent-device/references/logs-and-debug.md @@ -2,6 +2,22 @@ Logging is off by default in normal flows. Enable it on demand for debugging windows. App output is written to a session-scoped file so agents can grep it instead of loading full logs into context. +## Data Handling + +- Default app logs are stored under `~/.agent-device/sessions//app.log`. +- Replay scripts saved with `--save-script` are written to the explicit path you provide. +- Log files may contain sensitive runtime data; review before sharing and clean up when finished. +- Use `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS` to redact sensitive patterns at write time when needed. + +## Retention and Cleanup + +- Keep logging scoped to active debug windows (`logs clear --restart` before repro, `logs stop` after repro). +- Prefer bounded inspection (`grep -n`, `tail -50`) instead of reading full logs into context. +- Clear session logs when finished: + `agent-device logs clear` +- Close session to stop background logging state: + `agent-device close` + ## Quick Flow ```bash diff --git a/skills/agent-device/references/permissions.md b/skills/agent-device/references/permissions.md index 441849930e..d1857d1618 100644 --- a/skills/agent-device/references/permissions.md +++ b/skills/agent-device/references/permissions.md @@ -13,6 +13,14 @@ Use Automatic Signing in Xcode, or provide optional overrides: - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE` +Security guidance for these overrides: + +- These variables are optional and only needed for physical-device XCTest setup. +- Treat values as sensitive host configuration; do not share in chat logs or commit to source control. +- Do not provide private keys or unrelated secrets; use the minimum values required for signing. +- Prefer Xcode Automatic Signing when possible to reduce manual secret/config handling. +- For autonomous/CI runs, keep these unset by default and require explicit opt-in for physical-device workflows. + If setup/build takes long, increase: - `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (default `45000`, for example `120000`)