ESP32_Serial_Swiss_Army_Knife/docs/security_operations.md

Security operations — intermittent hobby use

This checklist is for a wireless serial cable used occasionally on a trusted network, not an Internet-facing appliance or a production-security certification. It covers existing firmware operations only: no dependency patches, crypto upgrades, secure-boot, encrypted-NVS, or eFuse changes are part of this scope.

Provision once, locally

• Use the physical UART0 administration console on a trusted computer. Native USB CDC is a separate UART1 serial-data path, not the admin console.
• Create the first administrator with user add <username> admin. Use a unique password; the prompt accepts 12–64 printable ASCII characters. Add a separate user account for ordinary serial use, especially over SSH: SSH admin opens administration, whereas SSH user opens UART1.
• Use unique Wi-Fi credentials, not passwords reused from other services. Configure station profiles using the Wi-Fi command reference; enter their passwords with wifi profile secret <slot>. If using the device AP, set its password with wifi ap secret. If the AP is unnecessary, select wifi ap policy off. Run wifi save to persist working Wi-Fi settings.
• Before entering network credentials into a client, check device identity locally: run web certificate info and ssh host-key info on trusted UART0. Compare the SHA-256 certificate fingerprint in the browser certificate viewer and the SSH host-key fingerprint in the SSH client with those local values. Record the verified fingerprints; do not blindly dismiss certificate or changed-key warnings.
• Keep passwords in a password manager. Generated account passwords (--generate) are displayed once; avoid terminal recording or sharing that output.

Each use

• Use only a trusted LAN or the device's password-protected AP. Do not configure router port forwarding or otherwise expose HTTPS/SSH to the Internet. A trusted network reduces exposure; it does not make every attached client trustworthy.
• Check unexpected identity warnings against UART0 before logging in. Keep UART0, native USB, and the connected RS-232 equipment physically controlled: local serial access is not protected by network account authentication.
• When finished, sign out of the browser and close SSH clients. Browser serial Disconnect alone is not sign-out.
• Prefer powering the device off when unused. If it must remain powered for USB serial use, run wifi stop from UART0 and check wifi status after the queued operation completes. This stops network access, not native USB UART1 access. To keep Wi-Fi disabled at the next boot, follow with wifi save. wifi start enables it again in RAM; save again only if that boot policy is wanted. Do not rely on a temporary stop surviving reboot without saving.

Change credentials or identity when needed

Use trusted UART0 for these operations to avoid losing a remote session mid-change. Rotate after suspected disclosure, a lost client key, or a change of owner/access; there is no need for a calendar-driven rotation ritual for this use case.

What changed	Built-in operation
Account password	user password <username> (no-echo prompt).
Authorized SSH client key	user show <username> to identify its index; user key delete <username> <0..2> --force, then user key add <username> to enter the replacement public key.
Account no longer needed	user delete <username> --force; the final administrator is protected.
Wi-Fi password	Change the router credential as appropriate, then wifi profile secret <slot>; for the device AP use wifi ap secret. Finish with wifi save.
HTTPS device identity	web certificate rotate --force.
SSH device identity	ssh host-key rotate --force.

Account changes invalidate that account's network sessions; identity replacement interrupts the affected service. Check command results, then verify new fingerprints through UART0 before updating browser trust or SSH known-host entries and reconnecting. Changing a password does not remove authorized SSH keys; review both after compromise. Identity rotation is not an account-password change. If an acknowledgement is lost, inspect current state on UART0 rather than blindly repeating the operation.

Recovery and backup limits

• Keep UART0 available for forgotten passwords, Wi-Fi mistakes, and network-service recovery. Native USB can still carry UART1 data when networking fails, but cannot repair accounts or identities; neither path promises uninterrupted service through reboot.
• For a healthy database, use normal UART0 account commands to repair access. user recover --force is only for an unavailable user database: it destroys that database's contents and rebuilds it empty, refuses a healthy database, and requires creating a new administrator afterward. It is not a forgotten-password reset.
• web reset --force replaces HTTPS certificate/private-key material only; ssh reset --force replaces SSH host-key material. Neither resets accounts or Wi-Fi. These are scoped recovery operations, not a whole-device factory reset.
• No supported configuration/credential/identity backup-export command was found in the application console. Keep a private reprovisioning record of settings, account names/roles, client public keys, and verified fingerprints; store passwords separately in a password manager. Do not expect status output to recover secrets or private keys. Reprovisioning may require accepting a newly verified device identity.
• Physical extraction or firmware replacement is not protected by this checklist. Treat a lost device or a raw flash copy as potentially exposing stored Wi-Fi secrets, private identities, and password verifiers. Rotation is not a secure flash-erasure claim.

Lightweight maintenance

Occasionally, and before a planned firmware update, review relevant ESP-IDF, wolfSSL/wolfSSH, and bundled web-library upstream release/security notes. If a relevant issue appears, stop network use until a separate upgrade decision is made; USB serial remains an option. Dependency upgrades and their validation are separate work, not an endless CVE audit or an implied promise that this firmware is vulnerability-free.

Commands and limits were checked against application sources and the command reference at f40c09c. This is source-reviewed operating guidance, not a build, hardware test, security audit, or verification of any individual device's flash/eFuse configuration.