diff --git a/src/02-templates/gbdialog.md b/src/02-templates/gbdialog.md index ccc4d0a9..019d0b88 100644 --- a/src/02-templates/gbdialog.md +++ b/src/02-templates/gbdialog.md @@ -2,6 +2,27 @@ The [`.gbdialog`](../chapter-02/gbdialog.md) package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior. +## ⚠️ System Limits & Safety + +All `.gbdialog` scripts run in a **sandboxed environment** with enforced limits to prevent abuse: + +| Limit | Value | Description | +|-------|-------|-------------| +| **Loop Iterations** | 100,000 | Maximum iterations per loop (WHILE/FOR) | +| **Script Timeout** | 300 seconds | Maximum execution time | +| **String Length** | 10 MB | Maximum string size | +| **Array Length** | 1,000,000 | Maximum array elements | +| **File Size** | 100 MB | Maximum file size for GET/SAVE | +| **API Calls** | 1,000/minute | Rate limit per user | + +**Important:** +- Loops automatically terminate if they exceed the iteration limit +- Scripts that run too long are forcefully stopped +- Excessive API calls return HTTP 429 (Too Many Requests) +- File operations are restricted to the bot's `.gbdrive` scope + +See [System Limits](../12-auth/system-limits.md) for complete documentation. + ## What is .gbdialog? `.gbdialog` files are written in a specialized BASIC dialect that controls: @@ -229,6 +250,9 @@ The system handles errors gracefully: - Runtime errors logged but don't crash - LLM provides fallback responses - Timeouts prevent infinite operations +- **Loop limit exceeded**: Script terminates with "Maximum iterations exceeded" error +- **Rate limit exceeded**: Returns HTTP 429 with `retry_after_secs` value +- **File too large**: Operation fails with "Limit exceeded for file_size" error ## Script Execution @@ -238,6 +262,9 @@ Scripts run in a sandboxed environment with: - Knowledge base search - Tool execution rights - External API access (configured) +- **Enforced resource limits** (see System Limits above) +- **No direct filesystem access** - only `.gbdrive` via keywords +- **Rate limiting** - excessive requests return 429 ## Migration from Traditional Bots diff --git a/src/07-gbapp/testing-safety.md b/src/07-gbapp/testing-safety.md new file mode 100644 index 00000000..432bb67d --- /dev/null +++ b/src/07-gbapp/testing-safety.md @@ -0,0 +1,351 @@ +# Testing and Safety Tooling + +This guide covers advanced testing and safety tools for General Bots development, including formal verification, undefined behavior detection, and memory safety analysis. + +## Overview + +General Bots prioritizes safety and correctness. While Rust's type system catches many errors at compile time, additional tooling can detect subtle bugs and verify critical code paths. + +## Standard Testing + +### Unit Tests + +```bash +cargo test +``` + +Run tests for a specific package: + +```bash +cargo test -p botserver +cargo test -p botlib +``` + +### Integration Tests + +```bash +cargo test --test integration +``` + +## Miri - Undefined Behavior Detection + +[Miri](https://github.com/rust-lang/miri) is an interpreter for Rust's mid-level intermediate representation (MIR) that detects undefined behavior. + +### When to Use Miri + +- Testing unsafe code blocks +- Detecting memory leaks in complex data structures +- Finding data races in concurrent code +- Validating pointer arithmetic + +### Running Miri + +```bash +# Install Miri +rustup +nightly component add miri + +# Run tests under Miri +cargo +nightly miri test + +# Run specific test +cargo +nightly miri test test_name + +# Run with isolation disabled (for FFI) +cargo +nightly miri test -- -Zmiri-disable-isolation +``` + +### Miri Limitations + +- **Slow execution** - 10-100x slower than native +- **No FFI** - Cannot call C libraries +- **No I/O** - Cannot perform actual I/O operations +- **Nightly only** - Requires nightly Rust + +### Recommended Usage for General Bots + +Miri is valuable for testing: +- `botlib` data structures and parsing logic +- BASIC interpreter core in `botserver` +- Custom serialization/deserialization code + +Not suitable for: +- HTTP handlers (requires I/O) +- Database operations (requires FFI) +- Full integration tests + +## Kani - Formal Verification + +[Kani](https://github.com/model-checking/kani) is a model checker that mathematically proves code properties. + +### When to Use Kani + +- Verifying critical algorithms +- Proving absence of panics +- Checking invariants in state machines +- Validating security-critical code + +### Running Kani + +```bash +# Install Kani +cargo install --locked kani-verifier +kani setup + +# Verify a function +cargo kani --function critical_function + +# Verify with specific harness +cargo kani --harness verify_limits +``` + +### Writing Kani Proofs + +```rust +#[cfg(kani)] +mod verification { + use super::*; + + #[kani::proof] + fn verify_loop_limit_check() { + let iterations: u32 = kani::any(); + let max: u32 = kani::any(); + + // Assume valid inputs + kani::assume(max > 0); + + let result = check_loop_limit(iterations, max); + + // Prove: if iterations < max, result is Ok + if iterations < max { + assert!(result.is_ok()); + } + } + + #[kani::proof] + fn verify_rate_limiter_never_panics() { + let count: u64 = kani::any(); + let limit: u64 = kani::any(); + + kani::assume(limit > 0); + + // This should never panic regardless of inputs + let _ = count.checked_div(limit); + } +} +``` + +### Kani Limitations + +- **Bounded verification** - Cannot verify unbounded loops +- **Slow** - Model checking is computationally expensive +- **Limited async support** - Async code requires special handling + +### Recommended Usage for General Bots + +Kani is valuable for: +- Verifying `botlib::limits` enforcement +- Proving rate limiter correctness +- Validating authentication logic invariants +- Checking BASIC parser edge cases + +## AddressSanitizer (ASan) + +AddressSanitizer detects memory errors at runtime. + +### Running with ASan + +```bash +# Build and test with AddressSanitizer +RUSTFLAGS="-Z sanitizer=address" cargo +nightly test + +# For a specific package +RUSTFLAGS="-Z sanitizer=address" cargo +nightly test -p botserver +``` + +### What ASan Detects + +- Use-after-free +- Buffer overflows +- Stack buffer overflow +- Global buffer overflow +- Use after return +- Memory leaks + +### ASan Configuration + +```bash +# Set ASan options +export ASAN_OPTIONS="detect_leaks=1:abort_on_error=1:symbolize=1" + +# Run tests +RUSTFLAGS="-Z sanitizer=address" cargo +nightly test +``` + +## ThreadSanitizer (TSan) + +Detects data races in multi-threaded code. + +```bash +RUSTFLAGS="-Z sanitizer=thread" cargo +nightly test +``` + +### TSan Considerations + +- Requires `--target x86_64-unknown-linux-gnu` +- Incompatible with ASan (run separately) +- Higher memory overhead + +## MemorySanitizer (MSan) + +Detects uninitialized memory reads. + +```bash +RUSTFLAGS="-Z sanitizer=memory" cargo +nightly test +``` + +### MSan Requirements + +- Must compile all dependencies with MSan +- Most practical for pure Rust code +- Requires nightly toolchain + +## Ferrocene - Safety-Critical Rust + +[Ferrocene](https://ferrocene.dev/) is a qualified Rust compiler for safety-critical systems. + +### When to Consider Ferrocene + +Ferrocene is relevant if General Bots is deployed in: +- Medical devices +- Automotive systems +- Aerospace applications +- Industrial control systems +- Any context requiring ISO 26262, IEC 61508, or DO-178C compliance + +### Ferrocene vs Standard Rust + +| Aspect | Standard Rust | Ferrocene | +|--------|---------------|-----------| +| **Qualification** | None | ISO 26262, IEC 61508 | +| **Documentation** | Community | Formal qualification docs | +| **Support** | Community | Commercial support | +| **Cost** | Free | Commercial license | +| **Traceability** | Limited | Full requirement traceability | + +### Should General Bots Use Ferrocene? + +**For typical SaaS deployment: No** + +Ferrocene is overkill for: +- Web applications +- Business automation +- General chatbot deployments + +**Consider Ferrocene if:** +- Deploying GB in safety-critical environments +- Customer requires formal certification +- Regulatory compliance mandates qualified tooling + +### Alternative: Standard Rust + Testing + +For most deployments, comprehensive testing provides sufficient confidence: + +```bash +# Full test suite +cargo test --all + +# With coverage +cargo tarpaulin --out Html + +# Fuzzing critical parsers +cargo fuzz run parse_basic_script +``` + +## Recommended Testing Strategy + +### Development (Every Commit) + +```bash +cargo test +cargo clippy -- -D warnings +``` + +### Pre-Release + +```bash +# Full test suite +cargo test --all + +# Miri for unsafe code +cargo +nightly miri test -p botlib + +# AddressSanitizer +RUSTFLAGS="-Z sanitizer=address" cargo +nightly test + +# ThreadSanitizer (for concurrent code) +RUSTFLAGS="-Z sanitizer=thread" cargo +nightly test +``` + +### Critical Code Changes + +```bash +# Kani for formal verification +cargo kani --function critical_function + +# Extended fuzzing +cargo fuzz run target_name -- -max_total_time=3600 +``` + +## CI/CD Integration + +Example GitHub Actions workflow: + +```yaml +name: Safety Tests + +on: + push: + branches: [main] + pull_request: + +jobs: + miri: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@nightly + with: + components: miri + - run: cargo miri test -p botlib + + sanitizers: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@nightly + - run: RUSTFLAGS="-Z sanitizer=address" cargo test + + kani: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: model-checking/kani-github-action@v1 + - run: cargo kani --tests +``` + +## Summary + +| Tool | Purpose | When to Use | +|------|---------|-------------| +| `cargo test` | Unit/integration tests | Always | +| `miri` | Undefined behavior | Unsafe code changes | +| `kani` | Formal verification | Critical algorithms | +| `ASan` | Memory errors | Pre-release, CI | +| `TSan` | Data races | Concurrent code changes | +| `Ferrocene` | Safety certification | Regulated industries only | + +## See Also + +- [System Limits](../12-auth/system-limits.md) - Rate limiting and resource constraints +- [Security Features](../12-auth/security-features.md) - Security architecture +- [Building from Source](./building.md) - Compilation guide \ No newline at end of file diff --git a/src/12-auth/README.md b/src/12-auth/README.md index c93ce700..eae9ac21 100644 --- a/src/12-auth/README.md +++ b/src/12-auth/README.md @@ -1,10 +1,10 @@ # Chapter 12: Authentication & Security -User authentication and permission management for botserver. +User authentication, permission management, and resource protection for botserver. ## Overview -botserver provides enterprise-grade security with flexible authentication options and granular permissions. +botserver provides enterprise-grade security with flexible authentication options, granular permissions, and comprehensive rate limiting to prevent abuse. ## Authentication Methods @@ -30,7 +30,8 @@ END IF - **Password Hashing**: Argon2 with secure defaults - **Session Management**: Cryptographic tokens, configurable expiry -- **Rate Limiting**: Prevent brute force attacks +- **Rate Limiting**: Per-user and global limits with HTTP 429 responses +- **System Limits**: Loop protection, file size limits, resource constraints - **Audit Logging**: Track all authentication events - **Encryption**: AES-GCM for data at rest @@ -63,6 +64,7 @@ auth-lockout-duration,900 - [Compliance Requirements](./compliance-requirements.md) - GDPR, LGPD, HIPAA - [Permissions Matrix](./permissions-matrix.md) - Access control - [User vs System Context](./user-system-context.md) - Execution contexts +- [System Limits & Rate Limiting](./system-limits.md) - Resource constraints and abuse prevention ## See Also diff --git a/src/12-auth/security-checklist.md b/src/12-auth/security-checklist.md new file mode 100644 index 00000000..9770a2a6 --- /dev/null +++ b/src/12-auth/security-checklist.md @@ -0,0 +1,238 @@ +# Security Review Checklist for SaaS Deployment + +This checklist covers critical security considerations before deploying General Bots as a multi-tenant SaaS platform. + +## Pre-Deployment Security Audit + +### 1. Authentication & Authorization + +- [ ] **Password Security** + - [ ] Argon2id hashing with secure parameters + - [ ] Minimum password length enforced (12+ characters) + - [ ] Password complexity requirements enabled + - [ ] Breached password checking enabled + +- [ ] **Session Management** + - [ ] Cryptographically secure session tokens (256-bit) + - [ ] Session timeout configured (default: 1 hour idle) + - [ ] Session revocation on password change + - [ ] Concurrent session limits per user + +- [ ] **Multi-Factor Authentication** + - [ ] TOTP support enabled for admin accounts + - [ ] MFA enforcement for privileged operations + - [ ] Recovery codes securely generated and stored + +- [ ] **OAuth2/OIDC** + - [ ] State parameter validation + - [ ] PKCE enforcement for public clients + - [ ] Token rotation enabled + - [ ] Redirect URI validation (exact match) + +### 2. Rate Limiting & Resource Protection + +- [ ] **API Rate Limits** (from `botlib::limits`) + - [ ] Per-user limits: 1,000 requests/minute + - [ ] Per-user limits: 10,000 requests/hour + - [ ] Global limits prevent platform exhaustion + - [ ] HTTP 429 responses with `Retry-After` header + +- [ ] **Script Execution Limits** + - [ ] Loop iteration limit: 100,000 + - [ ] Script timeout: 300 seconds + - [ ] Recursion depth limit: 100 + - [ ] String length limit: 10 MB + +- [ ] **File & Upload Limits** + - [ ] Max file size: 100 MB + - [ ] Max upload size: 50 MB + - [ ] Max request body: 10 MB + - [ ] File type validation enabled + +- [ ] **Connection Limits** + - [ ] Max concurrent requests per user: 100 + - [ ] Max WebSocket connections per user: 10 + - [ ] Database connection pooling configured + +### 3. Input Validation & Injection Prevention + +- [ ] **SQL Injection** + - [ ] All queries use parameterized statements (Diesel ORM) + - [ ] Dynamic table names sanitized via `sanitize_identifier()` + - [ ] No raw SQL string concatenation + +- [ ] **Cross-Site Scripting (XSS)** + - [ ] HTML output properly escaped + - [ ] Content-Security-Policy headers configured + - [ ] X-Content-Type-Options: nosniff + +- [ ] **Path Traversal** + - [ ] File paths sanitized (no `..` allowed) + - [ ] Operations restricted to tenant's `.gbdrive` scope + - [ ] Symbolic links not followed + +- [ ] **Command Injection** + - [ ] No shell command execution from user input + - [ ] BASIC scripts sandboxed in Rhai runtime + +### 4. Data Protection + +- [ ] **Encryption at Rest** + - [ ] Database encryption enabled + - [ ] Object storage (MinIO) encryption enabled + - [ ] Secrets encrypted with AES-GCM + +- [ ] **Encryption in Transit** + - [ ] TLS 1.2+ required for all connections + - [ ] HTTPS enforced (no HTTP fallback) + - [ ] Internal service communication encrypted + +- [ ] **Secrets Management** + - [ ] API keys stored in environment variables + - [ ] No hardcoded credentials in code + - [ ] Secrets rotated regularly + - [ ] `.env` files excluded from version control + +- [ ] **Data Isolation** + - [ ] Multi-tenant data separation verified + - [ ] User cannot access other tenants' data + - [ ] Bot-level isolation enforced + +### 5. API Security + +- [ ] **URL Constants** (from `ApiUrls`) + - [ ] All routes use constants from `core/urls.rs` + - [ ] No hardcoded `/api/...` strings in route definitions + - [ ] URL parameters properly validated + +- [ ] **Request Validation** + - [ ] Content-Type validation + - [ ] Request size limits enforced + - [ ] Malformed JSON rejected + +- [ ] **Response Security** + - [ ] No sensitive data in error messages + - [ ] Stack traces disabled in production + - [ ] Consistent error response format + +### 6. Infrastructure Security + +- [ ] **Network Security** + - [ ] Firewall rules configured + - [ ] Internal services not exposed + - [ ] Database not publicly accessible + +- [ ] **Container Security** + - [ ] Non-root container users + - [ ] Read-only filesystem where possible + - [ ] Resource limits (CPU, memory) configured + +- [ ] **Logging & Monitoring** + - [ ] Authentication events logged + - [ ] Rate limit violations logged + - [ ] Error rates monitored + - [ ] Logs do not contain sensitive data (passwords, tokens) + +### 7. LLM & AI Security + +- [ ] **Prompt Injection Prevention** + - [ ] System prompts protected + - [ ] User input properly delimited + - [ ] Output validation enabled + +- [ ] **Token Limits** + - [ ] Max tokens per request: 128,000 + - [ ] LLM requests rate limited: 60/minute + - [ ] Cost monitoring enabled + +- [ ] **Data Privacy** + - [ ] No PII sent to external LLM APIs (if applicable) + - [ ] Conversation data retention policy defined + - [ ] User consent obtained + +### 8. Compliance + +- [ ] **GDPR** (EU) + - [ ] Data processing agreements in place + - [ ] Right to deletion implemented + - [ ] Data export capability available + - [ ] Privacy policy published + +- [ ] **LGPD** (Brazil) + - [ ] Legal basis for processing documented + - [ ] Data protection officer designated + - [ ] Breach notification process defined + +- [ ] **SOC 2** (Enterprise) + - [ ] Access controls documented + - [ ] Change management process + - [ ] Incident response plan + +## Deployment Verification + +### Pre-Production Testing + +```bash +# Run security-focused tests +cargo test --all + +# Check for memory issues +RUSTFLAGS="-Z sanitizer=address" cargo +nightly test + +# Verify rate limiting +curl -X POST http://localhost:8080/api/test \ + -H "Content-Type: application/json" \ + --data '{}' \ + --parallel --parallel-max 1000 + +# Expected: HTTP 429 after limit exceeded +``` + +### Production Hardening + +```bash +# Verify TLS configuration +openssl s_client -connect your-domain.com:443 -tls1_2 + +# Check security headers +curl -I https://your-domain.com + +# Expected headers: +# Strict-Transport-Security: max-age=31536000 +# X-Content-Type-Options: nosniff +# X-Frame-Options: DENY +# Content-Security-Policy: default-src 'self' +``` + +## Incident Response + +### In Case of Security Incident + +1. **Contain**: Disable affected accounts/services +2. **Investigate**: Review logs, identify scope +3. **Notify**: Inform affected users within 72 hours (GDPR) +4. **Remediate**: Fix vulnerability, rotate credentials +5. **Document**: Create incident report + +### Emergency Contacts + +- Security Team: security@your-domain.com +- Infrastructure: ops@your-domain.com +- Legal/Compliance: legal@your-domain.com + +## Regular Security Tasks + +| Frequency | Task | +|-----------|------| +| Daily | Review authentication failure logs | +| Weekly | Check rate limit violations | +| Monthly | Rotate API keys and secrets | +| Quarterly | Dependency vulnerability scan | +| Annually | Full security audit | + +## See Also + +- [System Limits](./system-limits.md) - Resource constraints +- [Security Features](./security-features.md) - Implementation details +- [Compliance Requirements](./compliance-requirements.md) - Regulatory requirements +- [Security Policy](./security-policy.md) - Organizational policies \ No newline at end of file diff --git a/src/12-auth/system-limits.md b/src/12-auth/system-limits.md new file mode 100644 index 00000000..134acb00 --- /dev/null +++ b/src/12-auth/system-limits.md @@ -0,0 +1,211 @@ +# System Limits & Rate Limiting + +General Bots enforces strict system limits to ensure fair resource usage, prevent abuse, and maintain platform stability for all users. + +## Overview + +All limits are defined in `botlib/src/limits.rs` and enforced throughout the platform. When limits are exceeded, the system returns HTTP 429 (Too Many Requests) with appropriate `Retry-After` headers. + +## Resource Limits + +### Loop & Recursion Protection + +| Limit | Value | Purpose | +|-------|-------|---------| +| `MAX_LOOP_ITERATIONS` | 100,000 | Prevents infinite loops in BASIC scripts | +| `MAX_RECURSION_DEPTH` | 100 | Prevents stack overflow from deep recursion | +| `MAX_SCRIPT_EXECUTION_SECONDS` | 300 | Maximum script runtime (5 minutes) | + +### File & Data Limits + +| Limit | Value | Purpose | +|-------|-------|---------| +| `MAX_FILE_SIZE_BYTES` | 100 MB | Maximum file size for processing | +| `MAX_UPLOAD_SIZE_BYTES` | 50 MB | Maximum upload size per request | +| `MAX_REQUEST_BODY_BYTES` | 10 MB | Maximum HTTP request body | +| `MAX_STRING_LENGTH` | 10 MB | Maximum string length in scripts | +| `MAX_ARRAY_LENGTH` | 1,000,000 | Maximum array elements | + +### Connection Limits + +| Limit | Value | Purpose | +|-------|-------|---------| +| `MAX_CONCURRENT_REQUESTS_PER_USER` | 100 | Per-user concurrent request limit | +| `MAX_CONCURRENT_REQUESTS_GLOBAL` | 10,000 | Platform-wide concurrent limit | +| `MAX_WEBSOCKET_CONNECTIONS_PER_USER` | 10 | WebSocket connections per user | +| `MAX_WEBSOCKET_CONNECTIONS_GLOBAL` | 50,000 | Platform-wide WebSocket limit | +| `MAX_DB_CONNECTIONS_PER_TENANT` | 20 | Database connections per tenant | + +### API Rate Limits + +| Limit | Value | Purpose | +|-------|-------|---------| +| `MAX_API_CALLS_PER_MINUTE` | 1,000 | Requests per user per minute | +| `MAX_API_CALLS_PER_HOUR` | 10,000 | Requests per user per hour | +| `MAX_LLM_REQUESTS_PER_MINUTE` | 60 | LLM API calls per minute | + +### LLM & Knowledge Base Limits + +| Limit | Value | Purpose | +|-------|-------|---------| +| `MAX_LLM_TOKENS_PER_REQUEST` | 128,000 | Maximum tokens per LLM request | +| `MAX_KB_DOCUMENTS_PER_BOT` | 100,000 | Documents per bot knowledge base | +| `MAX_KB_DOCUMENT_SIZE_BYTES` | 50 MB | Maximum document size for KB | +| `MAX_DB_QUERY_RESULTS` | 10,000 | Maximum query result rows | + +### Tenant & Resource Limits + +| Limit | Value | Purpose | +|-------|-------|---------| +| `MAX_DRIVE_STORAGE_BYTES` | 10 GB | Storage per tenant | +| `MAX_SESSIONS_PER_USER` | 10 | Concurrent sessions per user | +| `MAX_SESSION_IDLE_SECONDS` | 3,600 | Session timeout (1 hour) | +| `MAX_BOTS_PER_TENANT` | 100 | Bots per tenant | +| `MAX_TOOLS_PER_BOT` | 500 | Tools per bot | +| `MAX_PENDING_TASKS` | 1,000 | Pending automation tasks | + +## Rate Limiting Implementation + +### Using the Rate Limiter + +```rust +use botlib::{RateLimiter, SystemLimits, format_limit_error_response}; + +let rate_limiter = RateLimiter::new(SystemLimits::default()); + +async fn handle_request(user_id: &str) -> Response { + if let Err(limit_error) = rate_limiter.check_rate_limit(user_id).await { + let (status, body) = format_limit_error_response(&limit_error); + return (StatusCode::TOO_MANY_REQUESTS, body); + } + + // Process request... +} +``` + +### Checking Loop Limits in Scripts + +```rust +use botlib::{check_loop_limit, MAX_LOOP_ITERATIONS}; + +let mut iterations = 0; +loop { + check_loop_limit(iterations, MAX_LOOP_ITERATIONS)?; + iterations += 1; + + // Loop body... + + if done { + break; + } +} +``` + +### Response Format + +When a limit is exceeded, the API returns: + +```json +{ + "error": "rate_limit_exceeded", + "message": "Limit exceeded for api_calls_minute: 1001 > 1000 (max)", + "limit_type": "api_calls_minute", + "current": 1001, + "maximum": 1000, + "retry_after_secs": 60 +} +``` + +HTTP Headers: +- `Status: 429 Too Many Requests` +- `Retry-After: 60` +- `X-RateLimit-Limit: 1000` +- `X-RateLimit-Remaining: 0` +- `X-RateLimit-Reset: 1234567890` + +## BASIC Script Limits + +Scripts written in `.gbdialog` files are automatically protected: + +```basic +' This loop is safe - system enforces MAX_LOOP_ITERATIONS +WHILE condition + ' Loop body +WEND + +' FOR loops are also protected +FOR i = 1 TO 1000000 + ' Will stop at MAX_LOOP_ITERATIONS +NEXT +``` + +If a script exceeds limits: +- Loop iterations: Script terminates with "Maximum iterations exceeded" error +- Execution time: Script terminates after `MAX_SCRIPT_EXECUTION_SECONDS` +- Memory/string size: Script terminates with "Limit exceeded" error + +## Customizing Limits + +Administrators can customize limits per tenant via environment variables or configuration: + +```toml +[limits] +max_api_calls_per_minute = 2000 +max_drive_storage_bytes = 21474836480 # 20 GB +max_bots_per_tenant = 200 +``` + +## Best Practices + +### For Bot Developers + +1. **Avoid unbounded loops** - Always include exit conditions +2. **Paginate queries** - Don't fetch unlimited results +3. **Cache responses** - Reduce API calls with caching +4. **Use webhooks** - Instead of polling, use event-driven patterns +5. **Batch operations** - Combine multiple operations when possible + +### For System Administrators + +1. **Monitor rate limit hits** - Track 429 responses in analytics +2. **Set appropriate limits** - Balance security with usability +3. **Configure burst allowance** - Use `RATE_LIMIT_BURST_MULTIPLIER` for temporary spikes +4. **Clean up stale entries** - Rate limiter auto-cleans after 2 hours + +## Error Handling + +```rust +use botlib::{LimitExceeded, LimitType}; + +match result { + Err(LimitExceeded { limit_type, current, maximum, retry_after_secs }) => { + match limit_type { + LimitType::ApiCallsMinute => { + // Handle minute rate limit + } + LimitType::LoopIterations => { + // Handle infinite loop detection + } + _ => { + // Handle other limits + } + } + } + Ok(value) => { + // Success + } +} +``` + +## Security Considerations + +- **DDoS Protection**: Rate limits prevent resource exhaustion attacks +- **Abuse Prevention**: Per-user limits prevent single-user abuse +- **Fair Usage**: Ensures resources are shared fairly across all users +- **Cost Control**: LLM token limits prevent unexpected costs + +## See Also + +- [Security Features](./security-features.md) - Overall security architecture +- [API Endpoints](./api-endpoints.md) - API documentation +- [Compliance Requirements](./compliance-requirements.md) - Regulatory compliance \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b5784537..f8d320d8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -240,6 +240,7 @@ - [Service Layer](./07-gbapp/services.md) - [Creating Custom Keywords](./07-gbapp/custom-keywords.md) - [Adding Dependencies](./07-gbapp/dependencies.md) + - [Testing & Safety Tooling](./07-gbapp/testing-safety.md) # Part VIII - Bot Configuration @@ -329,6 +330,8 @@ - [Compliance Requirements](./12-auth/compliance-requirements.md) - [Permissions Matrix](./12-auth/permissions-matrix.md) - [User Context vs System Context](./12-auth/user-system-context.md) + - [System Limits & Rate Limiting](./12-auth/system-limits.md) + - [Security Checklist for SaaS](./12-auth/security-checklist.md) # Part XII - Device & Offline Deployment