Skip to main content
Version: 0.1.0

Runtime operational security reference

This guide is the runtime security operations view of PADAS: trust boundaries between the browser, Padas UI (the console), and the Motion Engine (console: Cores; tree: core/); the authentication surface each tier exposes; and deployment hardening choices that reduce runtime API exposure.

Related: Motion Engine TOML · Configuration & Runtime Engine · REST API Reference · Cores · Troubleshooting & Logs · Monitoring · Glossary · Users, roles & permissions · Run a sample pipeline

Trust boundaries and deployment model​

BoundaryTrust model
Browser ↔ consoleOperator login via POST /auth/login sets HTTP-only access_token / refresh_token cookies. Subsequent console API calls require a valid session signed with secrets in {PADAS_UI_HOME}/data/security/secret.json. The browser never directly authenticates to the engine for console workflows.
console ↔ engineService authentication: after enrollment, the console calls the engine over HTTPS using OAuth credentials stored on the engine host during enroll. Operators register host and port only in Cores—no token paste.
engine ↔ runtime objectsThe engine protects its HTTP API with TLS and authentication configured in padas.toml. The console uses the enrolled service identity for deploy and monitoring.

Separation of concerns: Operator login (who may open the console) uses console user accounts and session cookies. Service authentication (console to engine) is established by enrollment before you register a Core row. Direct engine API scripts (no console) may use separate engine API credentials—see Troubleshooting & Logs.

Padas UI bootstrap, RBAC, and operator profile​

First-time console administrator creation (POST /auth/init), session cookies, role checks (admin / user), and profile/password UX are documented in Users, roles & permissions. Treat /auth/init as part of ingress exposure: it remains reachable after initialization (returns 409 Conflict when a local user already exists).

Authentication and service accounts​

Motion Engine: direct API access (automation)​

When [api.auth].enabled = true, the engine requires Authorization: Bearer <secret> on /api/v1/* routes. For automation or leftover API-created objects (Troubleshooting & Logs), read the token from service-account.token on the engine host (path configured in padas.toml).

This path is separate from console enrollment: the console does not use this file when you register a Core after enroll.

curl -sS --tlsv1.2 --cacert /path/to/ca.pem \
  -H "Authorization: Bearer YOUR_CORE_TOKEN" \
  https://core.example.com:8999/api/v1/status

Engine token introspection: GET /api/v1/auth/token/status. Rotation: POST /api/v1/auth/token/refresh (Bearer required; per-IP refresh rate limit). Auth lockout: failed Bearer attempts increment per client IP derived from X-Forwarded-For / X-Real-IP; exceeding max_auth_attempts blocks even valid tokens until lockout_duration_secs elapses.

console: operator session vs engine access​

Mediation model: the browser trusts the console origin and session cookies. The console reaches the engine using credentials from enrollment—not a token the operator types into Cores.

MechanismRole
Operator sessionLogin and role checks gate console pages and mutating actions.
Engine callsAfter enrollment, deploy and monitoring use the service identity configured on the engine host. The browser never calls the engine directly for product workflows.

TLS and HTTPS​

Motion Engine ([api.tls])​

When [api.tls].enabled = true, the engine serves HTTPS with cert_file and key_file. When false, the engine serves plain HTTP. API client validation is on the client side: the engine does not install trust for outbound calls—align curl, the console, and scrapers with the certificate chain presented on 8999.

Self-signed operational realities: lab curl --insecure does not transfer trust to production browsers. TLS mismatch diagnostics: wrong scheme (http vs https), SNI/host mismatch, expired cert, or corporate MITM replacing chain—symptoms are TLS handshake errors before JSON.

[api.tls]
enabled = true
cert_file = "/var/lib/padas/etc/api.crt"
key_file = "/var/lib/padas/etc/api.key"

console​

Default packaged listen is HTTPS on port 9000 (see local-config.json under {PADAS_UI_HOME}/etc/). Production may terminate TLS at a reverse proxy instead. Browser trust vs server trust differ: the browser validates the console certificate; the console process validates the engine when it calls https://core:8999. Reverse proxy deployments must forward cookies, Authorization (if used upstream), X-Forwarded-For, and X-Real-IP consistently or auth lockout and audit client IPs skew.

Runtime API exposure​

Motion Engine​

host = "0.0.0.0" binds the full /api/v1/* surface (streams, tasks, connectors, query, system/reload, metrics). An auth-disabled engine ([api.auth].enabled = false) is dangerous outside isolated lab: any client on the network may mutate runtime state. There is no built-in IP allowlist. Operational isolation: bind 127.0.0.1, place the engine internal-only behind mesh/VPC, or front it with reverse proxy + mTLS / network policy.

console​

Mutating console routes require a valid operator session. /auth/login, /auth/logout, and /auth/init are outside the session gate—ingress restrictions must block unauthenticated /auth/init from the public Internet after bootstrap. Mutating API calls are audited (actor from session).

Operational security notes​

  • Bootstrap ordering: license → console admin setup → login → enroll the engine → register it under Cores (host/port) → verify from the console host (Cores → Verification).
  • Two identity layers: operator login = who may use the console; enrollment = how the console may call the engine.
  • Lockout correlation: Engine Bearer failures use X-Forwarded-For / X-Real-IP; mis-set proxies concentrate lockouts or hide attackers—validate reverse proxy implications before production.
  • Operational secrets: Motion Engine tree under $PADAS_HOME/core/ (padas.toml in etc/, data/security/service-account.token, TLS PEMs, enroll [core.auth.client] material) and PADAS_UI_HOME/data/security/ (users.json, secret.json, console TLS, data/security/s2s/ enroll registry). Platform $PADAS_HOME is /opt/padas. Filesystem permissions and secure backups of those trees are part of security posture—restore drills must not publish secrets into ticketing plaintext.

Runtime hardening checklist​

ControlOperator action
Enable TLSEngine [api.tls].enabled = true with real PEMs; console HTTPS or proxy termination consistent end-to-end.
Enable authEngine [api.auth].enabled = true; protect service_account_token_file on engine hosts used for direct API automation.
Restrict ingressNetwork policy / bind address; engine 8999 and console 9000 (or proxy front door) not on public Internet without controls.
Rotate engine API tokensUse engine POST /api/v1/auth/token/refresh for automation clients only; update scripts in the same change window. If console deploy auth fails, re-enroll or restart the engine after enroll—not a separate console token refresh API.
Secure $PADAS_HOME / PADAS_UI_HOMEOS permissions on the platform root (/opt/padas), the engine tree (core/), and the console tree (ui/); separate disks, encrypted volumes where policy demands.
Use reverse proxyCentralize TLS, optional WAF, canonical X-Forwarded-* handling.
Monitor failed authEngine 401 rates + lockout logs; console login rate limits on /auth/login; correlate with Monitoring incident windows.
Review runtime API exposureInventory who can reach engine /api/v1/* and console mutating routes from each VLAN.
Secure backupsRegistry DB, users.json, enroll material, and service-account.token (engine automation) contain operational secrets—encrypt at rest and restrict restore RBAC.

Operational security troubleshooting​

SymptomLikely runtime cause
401 after engine changeEnrollment incomplete, engine not restarted after enroll, or stale service credentials on the engine host. Re-run enrollment or confirm engine padas.toml auth blocks.
TLS trust mismatchThe console or curl missing the engine issuer CA; curl --cacert works but console does not—install enroll CA or align trust store.
Browser cookie / session issuesJWT expired and refresh failed; blocked cookies or wrong console origin.
Auth lockoutToo many bad Bearer attempts from one X-Forwarded-For IP at the engine; or console login rate limit.
Engine API unreachableNetwork, TLS scheme, or engine down—distinct from 401.
Deploy returns auth errorsEnroll incomplete or engine not restarted—see Installation — padas-motion.
Engine token refresh failuresEngine 429 refresh rate limit on direct API automation—separate from console enrollment.
Expired certificatesTLS handshake failure on the engine or console/proxy front door—renew PEMs, reload process or proxy.
Reverse proxy auth/header problemsStripped headers to the engine; malformed X-Forwarded-For breaking lockout or audits.

Deeper triage: Troubleshooting & Logs.

Security telemetry and monitoring​

  • Failed auth attempts: Engine logs + 401 spikes; console login audit entries.
  • Engine token refresh activity: Engine /api/v1/auth/token/refresh responses—for automation clients on the engine host, not console operators.
  • Runtime API access patterns: combine GET /api/v1/metrics with engine log windows for suspicious connector or deploy traffic.
  • Monitoring correlations: EPS/drop anomalies coincident with auth errors often indicate enrollment misconfiguration or overload—not “attacks” by default.
  • Suspicious connector behaviour: high error rates after credential change—distinguish connector secrets from engine Bearer vs console enroll paths.
  • Runtime anomaly investigation: use Monitoring first, then this document’s trust boundary table to decide which tier to fix.