Skip to content

Abuse Controls and Plugin Runtime Safety

Astra includes baseline abuse controls for repeated credential failures and a constrained plugin runtime model for extension safety.

Runtime adapters also support an origin policy for browser-facing deployments. Configure AdapterOriginPolicy on ASGI, FastAPI, Flask, Django, Robyn, or Litestar mounts to reject unsafe state-changing requests from untrusted origins and to emit CORS preflight headers only for allowed origins.

What Is Throttled

The runtime adapter applies throttling to repeated failures on:

  • /token
  • MFA verification
  • WebAuthn authentication finish

The admin UI applies throttling to:

  • repeated operator login failures
  • repeated sensitive operator actions such as config initialization and key rotation

Throttled responses return:

  • HTTP 429
  • a Retry-After header

Storage Model

Throttle state is backed by:

  • in-memory storage for in-memory service deployments
  • shared relational storage when the runtime uses shared persistence
  • a local shared SQLite-backed store for the admin UI under the runtime home

This means:

  • multi-process workers can enforce shared limits when they point at the same runtime persistence
  • local development still works without extra infrastructure

Diagnostics

Service and admin diagnostics now expose:

  • throttle storage kind
  • tracked bucket counts
  • currently blocked bucket counts
  • redacted bucket fingerprints for active blocks

Bucket identities are not exposed directly. Diagnostics show the throttle scope, such as oauth-token or mfa-verify, plus a short fingerprint.

Plugin Runtime Safety

Plugin hook and endpoint execution is guarded by:

  • namespace restrictions for plugin endpoints
  • duplicate route and method collision checks
  • timeout boundaries
  • validation/runtime failure classification
  • safe HTTP masking for plugin endpoint failures

Plugin endpoint failures return safe framework responses instead of leaking raw exceptions back to callers.

Plugin Audit Trail

Plugin execution diagnostics include:

  • hook and endpoint execution type
  • status
  • duration
  • fail-open or fail-closed mode
  • error classification when applicable

When Astra runs from a runtime home, recent plugin audit records are persisted to:

  • .astraauth/logs/plugin-runtime-audit.jsonl

The service package can surface these records through runtime_security_report(...), and the admin UI exposes them in its diagnostics dashboard and /api/security.

The CLI exposes the same operator report through:

astra security --home .astraauth --json

Plugin runtime audit records can be exported directly through:

astra plugin-audit --home .astraauth --json
astra plugin-audit --home .astraauth --plugin-name geo --status failed --json

Operator Guidance

  • Keep shared persistence enabled in production so runtime throttling is enforced across workers.
  • Review blocked-bucket counts if login or verification failures suddenly spike.
  • Review plugin audit logs when enabling new tenant plugins or debugging extension failures.
  • Treat plugin endpoint code as trusted runtime code. The runtime adds boundaries, but it does not make unsafe plugin logic safe by itself.

Investigating a Spike in Blocked Throttle Buckets

Use this sequence when blocked-bucket counts rise unexpectedly:

  1. Confirm the scope of the spike.
  2. astra security --home .astraauth --json
  3. check runtime_throttle.blocked_bucket_count

  4. check which scopes are blocked, such as oauth-token, mfa-verify, or webauthn-finish

  5. Separate runtime traffic from operator traffic.

  6. runtime signals appear under runtime_throttle
  7. admin operator signals appear under admin_ui_throttle

  8. if only admin UI buckets are blocked, investigate operator workflows first

  9. Correlate with event volume.

  10. inspect astra observability --home .astraauth --json

  11. review counters and recent admin actions

  12. Check plugin behavior if auth decisions recently changed.

  13. astra plugin-audit --home .astraauth --json
  14. filter to failures or a specific plugin if needed

  15. look for repeated validation or timeout failures that may be amplifying retries

  16. Review application and federation context.

  17. astra admin-audit --home .astraauth --json

  18. astra oidc-audit --home .astraauth --tenant-id <tenant> --json

  19. Decide whether this is abuse, user error, or system drift.

  20. abuse usually shows repeated blocked credential scopes from the same small set of buckets
  21. user error often shows isolated login or MFA failures after a rollout

  22. system drift often shows plugin failures, OIDC callback issues, or sudden verification mismatches

  23. Remediate deliberately.

  24. fix the underlying auth, MFA, plugin, or configuration problem
  25. do not disable throttling as a first response
  26. if you need to clear state, do it only after understanding whether the source is malicious or accidental