Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ joined this list.)
(`COMPOSER_HOST_REJECTED` vs a private-network refusal, `AGENT_UNAVAILABLE`, `AGENT_TIMEOUT`,
`EXECUTION_FAILED` with a `detail`). The Execute button is re-enabled after a failed request
instead of staying disabled.
- **Composer hosts can be added from the dashboard.** With `DevConsoleConfig.composerHostsEditable`
on (off by default), the Host allowlist card takes a hostname and a rejected request offers an
"Allow <host>" button, so trying another API no longer needs a rebuild. Added hosts last for the
- **Composer hosts can be added from the dashboard.** When the app sets `composerAllowedHosts`,
`DevConsoleConfig.composerHostsEditable` (on by default) lets the Host allowlist card take a
hostname, and a rejected request offers an "Allow <host>" button, so trying another API no longer needs a rebuild. Added hosts last for the
current run only, are audited, and cannot override hosts set by the app. The in-app Composer
screen uses the same live list.
- `sdk:composer` exposes `ResolvedComposerRequest.wireBody()` so every transport encodes bodies
Expand Down
56 changes: 36 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ DevConsole.initialize(
)
```

That's the setup. You now have crash and ANR reports, feature flags, and read-only inspectors for
That's the setup. You now have crash and ANR reports, feature flags, and editable inspectors for
SharedPreferences, SQLite, and files. Add one line to your HTTP client
(see [Wire up your network stack](#wire-up-your-network-stack)) and network, WebSocket, and MQTT
traffic show up too.
Expand Down Expand Up @@ -131,12 +131,12 @@ Then open the URL. With the default `BrowserSecurity.NONE`, the bare address is
| **Find in a capture** | Every detail screen has a find field that filters and highlights as you type. Network captures go further: step through hits with a counter and arrows, scope the search to the sections you choose, and match field names, values, or both. Any body can be expanded full-screen to read or copy. |
| **WebSocket & MQTT inspectors** | Connection lifecycles and every frame, inbound and outbound. MQTT rides the Eclipse Paho adapter. |
| **Mock rules** | Serve canned responses for matching requests (OkHttp), toggled from the dashboard, with deterministic priority matching. Wired by `installDevConsole` and editable out of the box. |
| **Request composer** | Make the device issue ad-hoc HTTP requests from the dashboard. Off by default, host-allowlist confinable. |
| **Request composer** | Make the device issue ad-hoc HTTP requests from the dashboard. Enabled by default; empty host lists allow any host, non-empty lists restrict destinations. |
| **Crash & ANR capture** | Uncaught exceptions and a main-looper watchdog with bounded all-thread dumps and breadcrumbs. Always delegates to any crash reporter you already have. |
| **Push timeline** | Record FCM (or any) push messages and their lifecycle: received → displayed → opened. The Firebase adapter uses reflection — no compile-time Firebase dependency. |
| **State & feature flags** | Snapshot host-registered state and override feature flags from the browser. |
| **Remote Config inspector** | Every Remote Config value active on the device, and where each one came from — server, in-app default, static fallback, or a local override — plus last fetch time and status. Read-only. The Firebase adapter uses reflection — no compile-time Firebase dependency. |
| **Data inspectors** | Browse SharedPreferences, SQLite (incl. a SQL console), and app files. Read-only by default; every edit surface is opt-in. |
| **Data inspectors** | Browse and edit SharedPreferences, SQLite (incl. a SQL console), and app files. All editing capabilities enabled; read-only operation is opt-in. |
| **Evidence tray & exports** | Flag anything, attach it to a bug report bundle or Markdown/Jira/GitHub clipboard text. Export HAR, Postman Collection, or a full session ZIP. |
| **Background keep-alive** | Default foreground service that keeps the server alive while your app is backgrounded. Enabled by the debug-only full runtime; the no-op runtime contributes no service or permissions. |

Expand Down Expand Up @@ -420,7 +420,8 @@ Not using Firebase? Implement `RemoteConfigProvider` for any other service — t
vendor-neutral, and [docs/REMOTE_CONFIG.md](docs/REMOTE_CONFIG.md) has a worked example. The
inspector is read-only: DevConsole never sets overrides and never triggers `fetch()` or `activate()`.

Values are redacted by key name before either surface sees them, matched separator-insensitively so
With `RedactionPolicy.recommended()`, values are redacted by key name before either surface sees
them, matched separator-insensitively so
`api_key` and `apiKey` are caught as well as `api-key`. It is still an allowlist, so a secret under
a name nobody listed is shown in full — extend `RedactionPolicy.sensitiveFieldNames` if you keep
anything sensitive in Remote Config.
Expand Down Expand Up @@ -565,32 +566,47 @@ devConsole {

## Security model

DevConsole deliberately exposes your app's internals to a browser, and two of its defaults trade
safety for a working first run. Know where the edges are:
DevConsole is a debug-only developer tool. Runtime security layers are **off by default and opt-in**.
Use these settings for shared networks or production-like data:

| Layer | Default | Enable protection |
|---|---|---|
| Redaction | Off | `DevConsoleConfig(redactionPolicy = RedactionPolicy.recommended())` |
| Rate limits | Off | `.withNetworkProtection(NetworkProtection(rateLimiting = true))` |
| Host/Origin checks | Off | `.withNetworkProtection(NetworkProtection(hostAndOriginChecks = true))` |
| Both network protections | Off | `.withNetworkProtection(NetworkProtection.recommended())` |
| Browser auth | `NONE` | `.withBrowserSecurity(BrowserSecurity.SESSION_CODE)` |
| Read-only editing | Off; all seven capabilities true | `.withEditingCapabilities(EditingCapabilities.readOnly())` |
| Composer host restriction | Any host (empty list) | `DevConsoleConfig(composerAllowedHosts = setOf("api.example.test"))` |
| Disable Composer | Enabled | `DevConsoleConfig(composerEnabled = false)` |
| Disable state mutations | Enabled | `DevConsoleConfig(stateMutationsEnabled = false)` |
| Disable screenshots | Enabled | `.withScreenshotPolicy(ScreenshotPolicy(enabled = false))` |

`withNetworkProtection` replaces the policy, so use `recommended()` to enable both switches.
The release/noop build guard is unchanged; static security headers remain on. `/api/v1/meta` reports
`redaction: "off" | "on"` and both effective `networkProtection` switches.

- **The dashboard speaks plaintext HTTP, and the default browser mode is open.** There is no TLS.
`BindingMode.AUTO` binds your device's network address whenever it can, and
`BrowserSecurity.NONE` means any client that can reach that address can read the dashboard and use
whatever editing capabilities the host enabled. Open mode still rejects browser mutations that
carry a foreign `Origin`; this protects against a cross-site browser request, not against another
client on the same reachable network. For a shared or untrusted network, pass
every editing capability by default. Host and Origin checks require
`NetworkProtection(hostAndOriginChecks = true)`. For a shared or untrusted network, pass
`BindingMode.LOOPBACK`, set `BrowserConfig(binding = BrowserBinding.LOOPBACK)`, or opt into
`BrowserSecurity.SESSION_CODE`.
- **The connect URL is a credential only in SESSION_CODE mode.** Holding a live `#code=` fragment
creates a session, with no approval step on the device. Codes are single-use and expire in five
minutes; sessions last 30. Treat that URL like a password. You can revoke sessions from the More
screen.
- **Redaction is an allowlist.** About 25 well-known field names and `Bearer` tokens get masked.
Custom header names, signed-URL query params, and PII inside bodies pass through verbatim. See
- **Redaction is opt-in.** `default()` and `none()` mask nothing. `recommended()` restores the
previous built-in sensitive field names; Authorization headers and Bearer text remain visible
unless you add rules. Unmatched custom fields and PII remain visible. See
[docs/SECURITY_AND_REDACTION.md](docs/SECURITY_AND_REDACTION.md).
- **Screenshots cannot be redacted.** Pixels don't have field names. Capture is **off by default**
- **Screenshots cannot be redacted.** Pixels don't have field names. Capture is **on by default**
and everything it produces is marked `UNREDACTED`.
- **Editing is off by default, except mocks.** Preferences/database/file writes and capture-rule
editing are each gated per surface via `EditingCapabilities`; the composer and state mutation have
their own `DevConsoleConfig` flags. All of those default to off/read-only. Mock editing is the one
exception: a mock rule writes nothing of yours, it only short-circuits DevConsole's own
interceptor, so it ships editable. `EditingCapabilities.readOnly()` still refuses everything
including mocks.
- **Editing is enabled by default.** Preferences, feature flags, database, files, mocks, request
execution, and capture rules all default to true, in constructors and Java Builders.
`EditingCapabilities.readOnly()` refuses everything including mocks. Composer and state mutations
have independent flags, both enabled by default.

For the full analysis, including what a malicious network peer or a co-installed app can and cannot
do, read [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md).
Expand All @@ -602,8 +618,8 @@ Three runnable samples under [`samples/`](samples/), one per integration style:
| Sample | Stack | Posture |
|---|---|---|
| [`compose-app`](samples/compose-app) | Jetpack Compose | Everything unlocked: all editing capabilities, composer, screenshots, OkHttp + Ktor (CIO) network demos, MQTT + WebSocket demos, in-app inspector, shake + floating-button open triggers |
| [`foundation-app`](samples/foundation-app) | Stock widgets, no UI framework | Everything at its locked-down default — the read-only contrast |
| [`views-java-app`](samples/views-java-app) | Java + XML, `ui-views` panel | Middle ground: mocks and capture rules editable, data read-only, async Java APIs, shake-to-open (LIGHT) + floating button — the same draggable one Compose hosts get, since it is a plain `View` on the decor view, not a Compose feature |
| [`foundation-app`](samples/foundation-app) | Stock widgets, no UI framework | Explicit read-only capabilities, Composer/state mutations disabled, screenshots disabled |
| [`views-java-app`](samples/views-java-app) | Java + XML, `ui-views` panel | Java Builder integration, editable defaults, async Java APIs, shake-to-open (LIGHT) + floating button |

```bash
./gradlew :samples:compose-app:assembleDebug
Expand Down
12 changes: 12 additions & 0 deletions docs/BUILD_VARIANTS_AND_PRODUCTION_SAFETY.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,18 @@ Run against `samples/compose-app` — the sample with every feature switched on
`FOREGROUND_SERVICE_SPECIAL_USE`, `POST_NOTIFICATIONS` and `INTERNET`, while its release APK lists
only `INTERNET` (the sample's own) and the auto-generated dynamic-receiver permission.

## Runtime security is opt-in

The release/noop guard is unchanged. It still refuses the full runtime in non-debuggable apps and
keeps protected variants on the noop artifact. Runtime defaults in an enabled debug build now favor
inspection: no redaction, no rate limiting or Host/Origin checks, open browser access, all editing
capabilities enabled, unrestricted Composer hosts, state mutations enabled, and screenshots enabled.
Opt in with `RedactionPolicy.recommended()`, `NetworkProtection.recommended()`,
`EditingCapabilities.readOnly()`, and `BrowserSecurity.SESSION_CODE`; set `composerEnabled = false`,
`stateMutationsEnabled = false`, and `ScreenshotPolicy(enabled = false)` when needed. The complete
[default/one-line configuration table](SECURITY_AND_REDACTION.md#opt-in-security-layers) and hardening
checklist cover shared networks and production-like data.

## Publication status

The artifacts are `com.github.devconsole-android.DevConsole:devconsole` (the full runtime, from `:sdk:full`) and
Expand Down
30 changes: 19 additions & 11 deletions docs/COMPOSER_AND_MOCKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,12 @@ authenticated session can open the Composer page in `SESSION_CODE` mode — see
[PROTOCOL_REFERENCE.md](PROTOCOL_REFERENCE.md#2-auth-handshake-session_code)), and either build a
request by hand or use "Copy redacted cURL to composer" from a captured Network
transaction (see [NETWORK_INSPECTOR.md](NETWORK_INSPECTOR.md)). The browser route
(`POST /api/v1/composer/execute`) is off by default — the host must set
`DevConsoleConfig.composerEnabled = true`, optionally with a `composerAllowedHosts` allowlist —
and is independent of the in-app inspector's own composer UI, which is instead gated by the host's
`EditingCapabilities.requestExecution` flag. See [THREAT_MODEL.md](THREAT_MODEL.md).
(`POST /api/v1/composer/execute`) is enabled by default. An empty `composerAllowedHosts` permits
any host; a non-empty set restricts every destination, including redirects, to those hosts.
Set `composerEnabled = false` to disable the browser Composer. The in-app inspector also requires
`EditingCapabilities.requestExecution`, which defaults to true. Use
`.withEditingCapabilities(EditingCapabilities.readOnly())` to refuse all inspector writes.
See [THREAT_MODEL.md](THREAT_MODEL.md).

### Calling an API with an access token (and why there is no CORS)

Expand Down Expand Up @@ -42,19 +44,20 @@ The result panel shows the status, timing, where it ran, the response headers an

### Adding a host without rebuilding

`composerAllowedHosts` is fixed when the app is built. To try another API without a rebuild, opt in
with `composerHostsEditable(true)`. The Composer's **Host allowlist** card then has an *Allow host*
An empty `composerAllowedHosts` (the default) lets the Composer reach any host, so there is nothing to
add. Once the app lists hosts, the list is fixed when the app is built; to try another API without a
rebuild, keep `composerHostsEditable` on (the default; `composerHostsEditable(false)` locks it). The Composer's **Host allowlist** card then has an *Allow host*
box (a pasted URL is reduced to its hostname), and a request rejected with `COMPOSER_HOST_REJECTED`
shows an **Allow \<host\>** button. Hosts added this way last until DevConsole stops, can be removed
from the same card, and are audited as `composer.host.add` / `composer.host.remove`. Hosts set by the
app cannot be removed from the dashboard, wildcards are not accepted, and at most 50 can be added.

The in-app Composer screen consults the same live list, so a host allowed from the dashboard also works
there while the server runs; with the server stopped it falls back to `composerAllowedHosts`. In the
samples, `compose-app` and `views-java-app` turn this on and `foundation-app` keeps its locked-down
defaults, where the card reads "The app fixes this list".
there while the server runs; with the server stopped it falls back to `composerAllowedHosts`. The
`views-java-app` sample lists hosts, so its card shows the editor; the other samples list none and permit
any host. With `composerHostsEditable(false)` the card reads "The app fixes this list".

Leave it off for anything reachable by other people: every added host widens where the device will send
Turn it off for anything reachable by other people: every added host widens where the device will send
requests, and in the default open mode that is anyone who can open the dashboard.

### Run on a host computer (macOS, Linux, Windows)
Expand Down Expand Up @@ -89,7 +92,12 @@ second, local lock, not a bypass.

Composer executions appear as first-class network events tagged `source=composer`, so they show up
in the Timeline and Network pages like any other captured request. Imported cURL and saved
collections never persist secret variable values by default.
collections follow the configured redaction policy. By default, secret values remain visible;
`DevConsoleConfig(redactionPolicy = RedactionPolicy.recommended())` opts into masking and secret
variable removal in collections. Rate budgets and Host/Origin checks are also opt-in through
`.withNetworkProtection(NetworkProtection.recommended())`. Browser authentication is independently
enabled with `.withBrowserSecurity(BrowserSecurity.SESSION_CODE)`. See the full
[layer/default table and hardening checklist](SECURITY_AND_REDACTION.md#opt-in-security-layers).

## Mocks

Expand Down
Loading
Loading