Repository navigation
Logging and Security
Why this SDK ships its own logging layer, how redaction works, and how to debug without leaking credentials.
The session token travels on every request as the X-User-Token header (and, by default, as the s= cookie), and JSON response bodies ({"meta": ..., "data": ...} envelopes can carry user_token, session_id, and similar fields). Naive DEBUG logging of requests/responses — the first thing anyone reaches for while debugging — will happily print these values verbatim. src/eero/logging.py exists so that debug logging is safe by default wherever it's used.
In practice, the modules that handle credentials or response bodies directly opt into it:
| Module | Logger | Why |
|---|---|---|
src/eero/api/auth.py |
get_secure_logger(__name__) |
Handles login, verify, refresh, session tokens |
src/eero/api/base.py (the transport) |
get_secure_logger(__name__) |
Logs parsed error envelopes at DEBUG only (the ERROR line carries just the status and method) — never the raw body text — so any credential-shaped field in an error envelope is redacted |
src/eero/api/auth_storage.py and almost every domain API |
get_secure_logger(__name__) |
Credential persistence, and domain modules whose envelopes may echo identifiers |
client.py, dns.py, security.py, support.py, transfer.py, ac_compat.py, burst_reporters.py
|
plain logging.getLogger(__name__)
|
Log method/URL/status and identifiers, not payloads |
Note: If you add your own debug logging around SDK calls — e.g. logging the raw envelope returned by
get_account()orget_devices()— useget_secure_logger()yourself. The SDK's internal loggers only protect the SDK's own log lines.
A drop-in replacement for logging.getLogger():
from eero.logging import get_secure_logger
_LOGGER = get_secure_logger(__name__)
_LOGGER.debug("Response: %s", {"user_token": "secret123", "status": "ok"})
# Output: Response: {'user_token': '[REDACTED:9chars]', 'status': 'ok'}get_secure_logger(name, sensitive_patterns=None, visible_chars=4) is @lru_cached — repeated calls with the same (name, sensitive_patterns, visible_chars) return the same adapter instance.
A custom sensitive_patterns= is scoped to the loggers you pass it to. The compiled regex is
cached per pattern set (_get_sensitive_regex() is keyed by the frozenset it receives), so
the SDK's own loggers, which use DEFAULT_SENSITIVE_PATTERNS, and a logger you build with your
own set never share or overwrite each other's regex. Combine the two with
add_sensitive_pattern() below when you want the defaults plus your own field names.
SecureLoggerAdapter(logger, extra=None, sensitive_patterns=DEFAULT_SENSITIVE_PATTERNS, visible_chars=4) wraps a standard logging.Logger. It overrides log(), and debug(), info(), warning(), error(), critical() and exception() all funnel through it, so every route into the adapter shares one redaction path. For each call it:
- Checks
isEnabledFor(level)first. A disabled level returns immediately: nothing is redacted, nothing is formatted, and no argument can make the call raise. - Redacts the message object and every positional format argument via
redact_sensitive(). - Merges the adapter's own
extracontext with the call'sextra=(the call's keys win) and redacts the result, so the values land on the log record as redacted attributes. - Hands the redacted values to the underlying
logging.Logger.log(), forwardingstacklevelso the record'spathname,linenoandfuncNamename your calling code rather thaneero/logging.py.
logger = get_secure_logger(__name__)
logger.warning("Auth cookie: %s", {"session_id": "abc123xyz"}, extra={"api_key": "topsecret"})
logger.log(logging.INFO, "Rows: %s", [{"token": "abc"}], extra={"secret": "x"})The positional argument and the extra dict are both redacted before the record is emitted, whether the call goes through a level method or log(). The objects you pass in are never modified.
from eero.logging import redact_sensitive
redact_sensitive({"password": "hunter2", "username": "alice"})
# {'password': '[REDACTED:7chars]', 'username': 'alice'}Behavior, verified against src/eero/logging.py:
-
Mappings, lists and tuples are inspected, in any combination and nesting: a top-level list of dicts, a tuple inside a dict, a list inside a list inside a dict. A bare string or other non-container value is returned unchanged —
redact_sensitive("s=abc123")does not redact anything, because there's no key to match against. Sensitive values must sit under a key to be caught. - The result is always a new structure; the argument is never mutated. A mapping comes back as a plain
dict(keys unchanged), aliststays alist, atuplestays atuple. Named tuples and other tuple subclasses come back as plain tuples, and their field names are not used for matching. - Matching is a case-insensitive substring search (
re.search, not an exact-match) onstr(key), so a key merely containing one of the patterns is redacted — e.g.access_key_idmatches onkey,X-Api-Keymatches onapi_key/key. Non-string keys (1,("a", "token"),None) never raise; they are matched by their text form and kept as the original key objects. - When a key matches, its whole value is replaced by the redacted form below, whatever the value's type.
- Recursion stops at 16 levels of nesting and at any reference cycle (a container that contains itself, directly or through other containers). The offending container is replaced by the fixed text
[REDACTED:cyclic-or-too-deep]instead of raisingRecursionError, so nothing below the cap can leak. A container that is merely referenced twice (no cycle) is redacted normally both times.
{
"token", "password", "passwd", "secret", "key", "credential",
"session_id", "session", "cookie", "auth", "api_key", "apikey",
"access_token", "refresh_token", "user_token", "bearer",
"authorization", "private",
"login", "email", "phone", "sms", "serial", "mac", "mac_address", "ssid",
}The first eighteen are credential-shaped (_ZERO_VISIBILITY_PATTERNS) and never show any of the value; the last eight are identifier-shaped and keep a short visible prefix.
| Input value | Redacted output |
|---|---|
None |
[NONE] |
True / False
|
[REDACTED:bool] |
123 / 1.5
|
[REDACTED:number] |
"" |
[EMPTY] |
"abc" (≤ visible_chars) |
[REDACTED:3chars] |
"secret123" (> visible_chars) |
secr...[REDACTED:9chars] |
The secr... prefix form applies only to identifier-shaped keys (email, phone, login, mac, ssid, serial, sms); credential-shaped keys always produce [REDACTED:Nchars] regardless of visible_chars.
raw = {"session_id": "s_9f8a7b6c5d4e", "email": "you@example.com", "status": "ok"}Before: {'session_id': 's_9f8a7b6c5d4e', 'email': 'you@example.com', 'status': 'ok'}
After: {'session_id': '[REDACTED:14chars]', 'email': 'you@...[REDACTED:15chars]', 'status': 'ok'}
Note:
phone/loginare identifier-shaped patterns: the first 4 characters remain visible. Credential-shaped keys (token,session*,cookie,auth*,password,secret,key, …) show only the length. To redact additional field names of your own, extend the pattern set withadd_sensitive_pattern()below.
Builds a pattern set that is the defaults plus your own field name. It does not mutate
DEFAULT_SENSITIVE_PATTERNS in place; it returns a new FrozenSet[str] you pass back into
get_secure_logger(). No cache reset is involved: the new set gets its own compiled regex the
first time it is used, independently of every other set:
from eero.logging import add_sensitive_pattern, get_secure_logger
patterns = add_sensitive_pattern("my_webhook_url")
logger = get_secure_logger(__name__, sensitive_patterns=patterns)
logger.debug("Config: %s", {"my_webhook_url": "https://hooks.example.com/T00/B00/XXXX"})
# Config: {'my_webhook_url': 'http...[REDACTED:38chars]'}Note:
add_sensitive_pattern()is pure — it touches no global state and has no effect on any existing logger; only loggers you build with the returned set use it.
⚠️ Warning:logging.basicConfig(level=logging.DEBUG)sets the root logger toDEBUG, which also enablesDEBUGfor every third-party library, includingaiohttp.aiohttp's own client logging atDEBUGincludes request/response headers — which includes theX-User-Tokenheader and theCookieheader (s=<token>), both carrying your live session token.SecureLoggerAdapteronly wraps loggers obtained throughget_secure_logger(); it cannot intercept or redactaiohttp's own log records.
The correct recipe: turn on DEBUG for this SDK's own loggers only, and keep aiohttp (and everything else) at INFO or WARNING:
import logging
# Root/default level for everything, including aiohttp.
logging.basicConfig(level=logging.WARNING)
# Debug this SDK's own logging (both the secure-logger-backed modules
# and the plain-logger-backed ones) without turning on aiohttp's
# header-dumping debug output.
logging.getLogger("eero").setLevel(logging.DEBUG)
logging.getLogger("aiohttp").setLevel(logging.WARNING)Before pasting logs into a GitHub issue:
- Confirm you did not set the root logger to
DEBUG(see the warning above) — if you did, re-run withlogging.getLogger("eero").setLevel(logging.DEBUG)instead and capture fresh output - Search the log for
X-User-Token:,Cookie:,Set-Cookie:,s=, or anysession_id/user_tokenvalue and redact manually — the SDK's redaction only covers what passes throughget_secure_logger() - Scrub the account email / phone from any
aiohttpor plain-logger output — the secure logger redacts them only when they appear as dict keys - Scrub the network's Wi-Fi password and guest network password if present in a
get_network()response dump - Truncate or omit full response bodies where possible — device MACs, hostnames, and nicknames are personally identifying
- Double-check any
extra={...}dicts you added yourself for custom debug statements
Verified in src/eero/api/base.py and src/eero/const.py:
| Behavior | Detail |
|---|---|
| 🔑 Credential placement | The session token is sent as the X-User-Token header (plus the s= cookie while send_legacy_cookie=True) only on requests on the configured API origin: the same scheme, hostname and effective port (an explicit :443 equals none on https), and no userinfo. Any other host, port or scheme, a URL carrying userinfo, or one whose authority cannot be parsed, is sent with no credential and a WARNING log line that names the reason and at most scheme://host, never the full URL. The token is never written to the shared aiohttp cookie jar |
| 🚫 Caller-supplied credential headers | A headers= dict containing X-User-Token, Cookie, or Authorization (any case) raises EeroValidationException before the request is sent |
| 🧹 Header validation | Every header value must be printable ASCII with no CR/LF (EeroValidationException otherwise) — header injection is impossible by construction |
| 🔁 Redirects | Never followed — allow_redirects=False is forced on every request and cannot be re-enabled (allow_redirects=True raises EeroValidationException); any 3xx response is rejected as an EeroAPIException rather than letting the token travel to a different host |
| 📏 Response size cap |
MAX_RESPONSE_BYTES = 10 * 1024 * 1024 (10 MiB) — the body is streamed in 64 KiB chunks and the request is aborted with EeroAPIException if the cap is exceeded |
| 🙈 Error bodies | The raw text of an error response is never embedded in an exception message or log line. The exception message is the recognised meta.error catalogue string (trimmed, lowercased) or the fixed label unrecognised error string; EeroAPIException and its subclasses prefix it with API error <status>: , while EeroAuthenticationException (all 401s), EeroRateLimitException and API-reported EeroValidationException carry no status in the message at all. meta.code, the raw body and the URL are never embedded (a byte count appears only for a 2xx whose body is not valid JSON). Read err.envelope / err.error_code / err.status_code for details; the parsed envelope is logged only through the secure logger |
| 🧾 URLs in logs | The request URL (which carries network, device and eero identifiers) is logged only at DEBUG (Request: …, Resource not found at …, Request to … timed out, Network error: … for URL: …, Retrying GET …). The server-supplied Location of a blocked redirect is likewise DEBUG-only. The ERROR lines for a timeout or a network failure carry just the HTTP method (and, for a network failure, the exception type), the WARNING for a GET retry carries just the attempt count, and the WARNING for a blocked redirect carries just the status. tests/api/test_log_hygiene.py fails if an identifier appears in any eero.api.base record above DEBUG
|
| 🔒 HTTPS only |
API_HOST = "https://api-user.e2ro.com"; API_ENDPOINT = api_endpoint("2.2"); device writes (DEVICE_UPDATE_ENDPOINT), multi-static-IP and secondary-WAN use api_endpoint("2.3") (see API Reference) — HTTPS-only hardcoded hosts; there is no HTTP fallback |
See Error Handling for the full status-to-exception mapping these behaviors feed into.
Session tokens are persisted at rest via KeyringStorage (OS keyring), FileStorage (owner-only 0600 JSON file), MemoryStorage, or ChainedStorage combining the two — selected by the use_keyring / cookie_file arguments on EeroClient. See Credential Storage for the full backend selection logic.
AuthCredentials (the record every backend loads and saves) leaves session_id out of its repr(), so printing, f-string formatting or a traceback that shows the record never exposes the token. Equality and to_dict() / from_dict() still include it.
⚠️ Warning: This SDK talks to a reverse-engineered, undocumented Eero Cloud API. It is not affiliated with or endorsed by Eero or Amazon. Only use it against Eero accounts you own — logging in against an account you don't control, or attempting to enumerate/brute-force the OTP flow, is misuse of someone else's account and network.
-
Error Handling — the
EeroExceptionhierarchy and HTTP status mapping - Credential Storage — keyring, file, and memory storage backends
- Authentication — the OTP login flow and session lifecycle
- Configuration — client setup & options
- Troubleshooting — common issues & fixes
eero-api — unofficial async Python client for the Eero cloud API. Not affiliated with or endorsed by Eero.
This wiki is generated from wiki/ in the main repository — edit there, not here. · MIT License