Skip to content

security.mdx

Latest commit

 

History

History
330 lines (234 loc) · 18.4 KB

security.mdx

File metadata and controls

330 lines (234 loc) · 18.4 KB
title Security
description Agentbot security practices and trust guarantees

Security & Trust

Agentbot is committed to keeping your data safe. Here's our security posture.

<img src="https://indigo-decent-condor-546.mypinata.cloud/ipfs/bafybeibstpvk6pqo23ks3vork3yzr6ns5mdeltkv5snrkpgxn3j6pkgoau" alt="Agentbot security" height="360" style={{borderRadius: '12px', width: '100%', objectFit: 'cover', marginBottom: '24px'}} />

Security Overview

Category Status Notes
Data Encryption ✅ TLS 1.3 in transit
API Authorization ✅ Session-based auth + JWT middleware, timing-safe key comparison, HMAC-SHA256 signature verification on backend user context headers
Data Isolation ✅ Row-level security (RLS) policies
Bot Detection ✅ Automated request filtering on sensitive endpoints
Input Validation ✅ Allowlist + sanitization
Rate Limiting ✅ Per-IP limits (120/min general, 30/min AI, 5/min deploys and provisioning)
CORS ✅ Restricted to allowed origins (no wildcard)
SSRF Protection ✅ Webhook URLs validated against private/internal IP ranges
A2A Authentication ✅ Message verification enforced before delivery
Audit Logging ✅ All actions logged, including per-payment audit trail
Payment Validation ✅ Amount limits ($100 max), recipient address format verification (EVM/Solana)
Webhook Signatures ✅ Svix verification (Resend), timing-safe secret (Railway), constructEvent (Stripe)
CSPRNG Tokens ✅ Invite codes and agent IDs use crypto.randomBytes
Session Signing ✅ Farcaster session tokens are HMAC-SHA256 signed with expiry
File Upload Safety ✅ Dotfile rejection, filename sanitization, 128-character limit

Skill Security Matrix

Skill Input Validation Sanitization User Data External Calls
Visual Synthesizer ✅ ✅ ❌ ✅ (Replicate)
Track Archaeologist ✅ ✅ ❌ ❌
Setlist Oracle ✅ ✅ ❌ ❌
Groupie Manager ✅ ✅ ✅ (demo) ❌
Royalty Tracker ✅ ✅ ❌ ❌
Demo Submitter ✅ ✅ ✅ (demo) ❌
Event Ticketing ✅ ✅ ✅ (email) ❌
Event Scheduler ✅ ✅ ❌ ❌
Venue Finder ✅ ✅ ❌ ❌
Festival Finder ✅ ✅ ❌ ❌

Bot detection

Sensitive API endpoints are protected by bot detection to prevent automated abuse. Protected endpoints return a 403 status code when a request is identified as coming from an automated source.

Protected endpoints:

Endpoint Purpose
/api/register Prevents fake account creation
/api/auth/forgot-password Blocks automated password reset abuse

Requests from standard web browsers are not affected. Automated clients such as scripts or bots may be blocked. If you are building a legitimate integration and receive a 403 response, ensure your requests originate from an environment that supports browser-level verification.

Trust Principles

1. Minimal Data Collection

  • We don't store prompts or generated images permanently
  • Demo skills use in-memory data that resets on restart
  • No user data sent to third parties (except Replicate for image generation)

2. Input Sanitization

All user inputs are:

  • Length-limited (max 100-500 chars depending on field)
  • Type-checked (strings, arrays, numbers)
  • Allowlist-validated (enum values must match predefined lists)
  • HTML/JS stripped (<> characters removed)

3. API Key Security

  • Replicate API tokens stored in server-side environment variables
  • Never exposed to client-side code
  • Used only for image generation requests

4. Read-Only Skills

Track Archaeologist, Setlist Oracle, Royalty Tracker, Venue Finder, Festival Finder, and Event Scheduler are read-only:

  • No user data stored
  • No external API calls
  • Uses only in-memory mock catalog
  • Safe for public demo use

Row-level security

All user-scoped database tables are protected by PostgreSQL row-level security (RLS) policies. Each authenticated request sets a user context at the database level before any query executes, so users can only read and modify their own data.

Protected tables

Table Policy Isolation key
User user_isolation id
Agent agent_isolation userId
ScheduledTask task_isolation userId
AgentMemory memory_isolation userId
AgentFile file_isolation userId
InstalledSkill skill_isolation userId
AgentSwarm swarm_isolation userId
Workflow workflow_isolation userId
Wallet wallet_isolation userId
ApiKey apikey_isolation userId
Account account_isolation userId
Session session_isolation userId

Admin bypass

Users with the admin role bypass RLS policies and can access all rows across tenants. Admin access is determined by the role column on the User table.

How it works

  1. The auth middleware verifies the JWT and extracts the userId.
  2. Before any database query, the middleware calls set_current_user_id(userId) to set a PostgreSQL session variable.
  3. RLS policies on each table compare the row's userId (or id for the User table) against the session variable.
  4. Queries automatically return only rows belonging to the authenticated user.

RLS is enforced at the database level and cannot be bypassed by application code. Even if a query omits a WHERE clause, only the authenticated user's rows are returned.

Auth middleware

The backend API uses auth middleware that runs before protected endpoints. API key comparison uses crypto.timingSafeEqual to prevent timing-based key enumeration. Two middleware functions are available: the inline authenticate function on the main router, and a standalone requireAuth middleware that can be applied to individual route handlers not mounted through the main router.

Authentication flow

  1. The client includes a Bearer token in the Authorization header.
  2. The middleware performs a constant-time comparison of the token against the server key.
  3. On success, the middleware attaches userId, userEmail, and userRole to the request and sets the RLS context.
  4. On failure, the endpoint returns one of the error codes below.

HMAC signature verification

The backend authenticate middleware verifies user context headers using HMAC-SHA256 signatures. When the frontend proxy forwards requests to the backend, it signs the user context (userId:userEmail:userRole) with a shared secret and includes the signature in the x-user-signature header. The backend verifies this signature before trusting the forwarded user identity.

The signing secret is read from HMAC_SECRET, falling back to INTERNAL_API_KEY. When the secret is configured, all requests with user context headers must include a valid signature. See the API reference for header details and error codes.

Error codes

Code HTTP status Description
AUTH_REQUIRED 401 No Authorization header or missing Bearer prefix
TOKEN_INVALID 401 JWT signature verification failed or token has expired
SIGNATURE_REQUIRED 401 HMAC secret is configured but no x-user-signature header was provided
INVALID_SIGNATURE 401 The HMAC-SHA256 signature does not match the expected value
AUTH_ERROR 500 Unexpected error during authentication
ADMIN_REQUIRED 403 Endpoint requires admin privileges and the authenticated user is not an admin

Admin endpoints

Endpoints that require admin access use an additional requireAdmin check after authentication. The admin check compares the authenticated user's email against the ADMIN_EMAILS environment variable using a case-insensitive match. Non-admin users receive a 403 response with code ADMIN_REQUIRED.

Header stripping

Both the backend API and the web frontend strip or reject requests that include headers commonly used to bypass URL-based access controls. The following headers are removed from every inbound request before it reaches any route handler:

Header Reason
X-Original-URL Prevents IIS/reverse-proxy URL override attacks
X-Rewrite-URL Prevents IIS/reverse-proxy URL rewrite attacks
X-Forwarded-Host Prevents host header injection and routing manipulation

On the backend API, these headers are deleted in a global middleware that runs before all routes. On the web frontend, X-Original-URL and X-Rewrite-URL are additionally scanned for injection patterns and the request is rejected with a 400 status if a suspicious payload is detected.

If your reverse proxy or CDN injects any of these headers, they will be silently removed. Do not rely on them for application logic.

Web API security middleware

The web frontend wraps API routes with security middleware that provides:

  • Rate limiting — per-IP request limits
  • DDoS protection — automated request filtering
  • Bot detection — blocks automated abuse on sensitive endpoints
  • SQL injection prevention — request parameters and body are scanned for injection patterns
  • XSS prevention — payloads containing script tags or event handlers are rejected
  • JSON validation — Content-Type enforcement and body parsing on mutation endpoints
  • CSRF protection — token-based verification using the x-csrf-token or x-xsrf-token header, enforced on the login endpoint and all sensitive mutation routes
  • Header stripping — bypass headers (X-Original-URL, X-Rewrite-URL, X-Forwarded-Host) are removed or rejected

Route protection levels

Level Wrapper Includes
Public SecureRoute.public Rate limiting, bot detection, input validation
Protected SecureRoute.protected Public checks + session or API key authentication
Mutation SecureRoute.mutation Protected checks + POST-only enforcement
JSON SecureRoute.json Public checks + POST-only + JSON content-type validation
Sensitive SecureRoute.sensitive Protected + POST-only + JSON validation + CSRF token

Error codes

HTTP status Description
400 Invalid JSON body, missing Content-Type: application/json, or injection pattern detected in request
401 Missing authentication credentials
403 Invalid or missing CSRF token
405 HTTP method not allowed (non-POST request on a mutation endpoint)
429 Too many failed authentication attempts from the same IP

SSRF protection

Webhook URLs are validated before any outbound request is made. URLs that resolve to private or internal IP ranges are rejected, including:

  • 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • 127.0.0.0/8 (localhost) and ::1
  • Link-local and other reserved ranges

This prevents server-side request forgery (SSRF) attacks where an attacker could use webhook configuration to probe internal services.

Agent-to-agent authentication

All agent-to-agent (A2A) messages are verified before delivery. The verifyMessage() check runs before deliverMessage(), ensuring that unauthenticated A2A messages are blocked. Additionally, negotiation actions (accepting or declining bookings) enforce ownership checks — only the originating agent can modify its own bookings.

CORS

The backend API restricts CORS to an explicit allowlist. The ALLOWED_ORIGINS environment variable accepts a comma-separated list of permitted origins. When unset, the API defaults to a built-in allowlist rather than accepting all origins. Wildcard (*) origins are not supported. Requests from unlisted origins receive a CORS error. Credentials are supported.

The X-Powered-By header is disabled on both the API (Express) and the web frontend (Next.js) to reduce fingerprinting surface.

HTTP security headers

All web frontend responses include the following security headers:

Header Value Purpose
Content-Security-Policy Restrictive policy with default-src 'self', base-uri 'self', object-src 'none', form-action 'self', and upgrade-insecure-requests Limits sources for scripts, styles, images, and connections. Restricts <base> tags and form targets to same-origin, blocks plugin content, and forces HTTPS for subresource requests.
X-Frame-Options DENY Prevents clickjacking by blocking iframe embedding
X-Content-Type-Options nosniff Prevents MIME type sniffing
Referrer-Policy strict-origin-when-cross-origin Limits referrer information sent to external sites
Permissions-Policy camera=(), microphone=(), geolocation=() Disables access to sensitive browser APIs
Cross-Origin-Opener-Policy same-origin-allow-popups Isolates browsing context from cross-origin windows
Strict-Transport-Security max-age=63072000; includeSubDomains; preload Enforces HTTPS for two years, including all subdomains

Cache control

API responses include no-cache, no-store, must-revalidate to prevent caching of sensitive data. Static assets under /public, /_next, and /assets use public, max-age=31536000, immutable for long-term caching.

Known limitations

Demo mode

Currently skills run in demo mode. In production:

  • API rate limits will be per-user

In-memory storage

Groupie Manager uses in-memory Map storage. Data is:

  • Lost on server restart
  • Not shared between server instances
  • Only for demonstration purposes

In-memory rate limiting (cold starts)

The web API security middleware uses in-memory stores for rate limiting, failed auth tracking, and bot detection. On serverless platforms (such as Vercel), this state resets on every cold start. For persistent rate limiting in production, configure KV_REST_API_URL and KV_REST_API_TOKEN to use Redis-backed storage. Without Redis, rate limits may be temporarily bypassed after a cold start until the in-memory counters rebuild.

Social post rate limiting and duplicate detection always use Upstash KV (via KV_REST_API_URL / KV_REST_API_TOKEN) and are not affected by cold starts. See Social post rate limits for the per-agent daily limits.

Reporting Issues

Found a security issue? Email security@raveculture.xyz or open a GitHub issue.

Google RISC Protocol

Agentbot implements Google's RISC (Risk Incident Sharing and Collaboration) protocol for enhanced OAuth security. Two endpoints handle RISC events, each serving a different role.

What is RISC?

RISC enables real-time security event sharing between Google and Agentbot. When Google detects a security incident (compromised account, suspicious activity, etc.), it sends a webhook to Agentbot to take immediate action.

Endpoints

Endpoint Purpose
POST /api/security/risc Cross-Account Protection receiver with token validation, event deduplication, and hijacking-specific responses
POST /api/auth/google/risc Legacy RISC webhook that revokes sessions on security events

The /api/security/risc endpoint is the primary receiver for Google Cross-Account Protection. It validates the SET (Security Event Token) JWT against Google's signing keys, checks the issuer and audience claims, deduplicates events using the jti claim, and takes targeted action depending on the event type. See the API reference for full details.

Supported events

Event /api/security/risc action /api/auth/google/risc action
account-disabled (hijacking) Disables Google Sign-in and invalidates all sessions Revokes all sessions
account-disabled (other) Invalidates all sessions Revokes all sessions
account-enabled Re-enables Google Sign-in No action taken
sessions-revoked Invalidates all sessions Revokes all sessions
tokens-revoked Revokes stored OAuth tokens and invalidates sessions Not handled
account-credential-change-required Logged for monitoring Not handled
verification Acknowledged (used during setup) Not handled
account-compromised Not handled Revokes all sessions
identifier-changed Not handled Revokes all sessions

The /api/security/risc endpoint matches users by Google subject ID (sub) or email address. The /api/auth/google/risc endpoint matches by email only.

Event deduplication

The /api/security/risc endpoint deduplicates events using the jti (JWT ID) claim. Each event is stored in the risc_events table with a unique constraint on the jti column. Duplicate events are acknowledged but not processed again.

Token validation

The /api/security/risc endpoint validates incoming SET JWTs by:

  1. Verifying the issuer is https://accounts.google.com/
  2. Checking the audience matches a configured GOOGLE_CLIENT_ID
  3. Fetching Google's RISC signing keys from the JWKS endpoint discovered via https://accounts.google.com/.well-known/risc-configuration (keys are cached for 24 hours)
  4. Matching the signing key by kid header claim
  5. Verifying the RS256 signature using the Web Crypto API (crypto.subtle) with the matched RSA public key

Security response

When a RISC event is received:

  1. Immediate: Disable Google Sign-in (for hijacking events) or invalidate sessions
  2. Audit: Log event type and affected user for security review
  3. Recovery: User must re-authenticate on next visit

Configuration

RISC events are configured in Google Cloud Console:

  1. Go to APIs & Services → Google RISC API
  2. Add the webhook URL: https://agentbot.sh/api/security/risc
  3. Configure event types to receive
  4. Set delivery method (push or poll)

The endpoint requires the GOOGLE_CLIENT_ID environment variable. Multiple client IDs can be provided as a comma-separated list.

Reference