Security Practices

Security Practices

This document outlines how to deploy AWAS safely: protecting users, infrastructure, and data while enabling AI automation.

Security Model Overview

AWAS describes actions; it does not grant authority. Sites remain in full control via authentication, authorization, and rate limiting. Treat agents like untrusted automation clients.

Principles:

• Least privilege and explicit consent
• Defense in depth (client, edge, app, data)
• Transparent auditing and revocation

Rate Limiting and Abuse Protection

• Global limits: e.g., 100 requests/hour per IP or token.
• Action-level limits: tighter caps on mutation (POST/PUT/DELETE) vs reads.
• Dynamic throttling on anomaly heuristics (sudden spikes, high error rates).
• 429 with Retry-After; expose quotas in response headers.
• Use circuit breakers for downstream dependencies.

Example headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1730179200

Authentication and Authorization

Supported patterns:

• OAuth2/OIDC with fine-grained scopes (preferred)
• API keys bound to org/project with rotation policy
• Session cookies with CSRF protection for browser flows

Best practices:

• Mark authentication.required per manifest and per action.
• Use short-lived access tokens; refresh via OIDC.
• Scope tokens to read vs write; require elevated scopes for sensitive actions.
• Enforce IP allowlists for admin actions.

Manifest example:

{
  "authentication": {
    "required": true,
    "methods": ["oauth2"],
    "oauth2": {
      "authorizationUrl": "https://auth.example/authorize",
      "tokenUrl": "https://auth.example/token",
      "scopes": ["orders:read", "orders:write"]
    }
  }
}

Agent Permissioning and Consent

• Human-in-the-loop: require explicit user confirmation for destructive actions (e.g., checkout, delete).
• Capability negotiation: publish actions and optional x-required-scopes.
• Per-agent allowlists/denylists, with per-tenant policy.
• Use signed intents or one-time tokens for high-risk actions.

UI safeguards:

• Add data-awas-action-level="danger" on destructive buttons.
• Require re-auth + MFA for irreversible operations.

Privacy and Data Minimization

• Collect only necessary parameters; avoid PII unless essential.
• Mark sensitive fields with x-sensitive: true in parameters.
• Redact logs and telemetry; never log secrets or full payloads.
• Support data retention controls; default to short retention (e.g., 7–30 days).
• Provide DSR endpoints and document them.

Parameter example:

{
  "name": "email",
  "type": "string",
  "format": "email",
  "required": true,
  "x-sensitive": true
}

Input Validation and Output Encoding

• Validate all inputs per JSON Schema constraints; reject on violation with 400 + details.
• Enforce server-side validation—do not rely on client hints.
• Encode outputs to prevent injection in HTML/JS contexts.

Transport and Storage Security

• Enforce HTTPS with HSTS; redirect HTTP to HTTPS.
• Use TLS 1.2+ and modern cipher suites.
• Encrypt secrets at rest; use a KMS/HSM.

Monitoring, Audit, and Incident Response

• Log action invocations with timestamps, actor, scope, result, and latency.
• Provide correlation IDs; return them to clients via X-Request-ID.
• Detect anomalies: high 4xx/5xx, auth failures, unusual parameter combos.
• Maintain runbooks and on-call escalation.

Threat Modeling and Risk Minimization

Common threats and mitigations:

• Credential stuffing: MFA, IP throttling, WebAuthn.
• Scraping: rate limits, watermarking, canary payloads, delay tactics.
• Injection: strict validation, parameterized queries, CSP.
• CSRF: SameSite cookies, CSRF tokens for state-changing actions.
• SSRF: outbound allowlists, metadata protection.

How AWAS Minimizes Risk

• Declarative manifests reduce agent guesswork and random crawling.
• Explicit parameters constrain inputs to safe, known shapes.
• Action-level rate limits and scopes restrict blast radius.
• Strong selectors reduce brittle automation that can bypass safeguards.

Compliance Considerations

• Align with SOC 2, ISO 27001 controls for change management and access.
• For GDPR/CCPA: document purposes, consent, DSR workflows.
• Keep data maps for parameter flow and retention.

Security Checklist

• All sensitive actions require auth and elevated scopes
• Rate limits configured globally and per action
• Input validation enforced server-side
• Logs redacted and retention defined
• TLS and HSTS enabled
• Monitoring and alerting active
• Incident runbooks documented