Add security checklist, system limits, testing safety docs

2025-12-28 11:50:51 -03:00 · 2025-12-28 11:50:51 -03:00 · c7bc1355c2
commit c7bc1355c2
parent 3f96aa6e1c
6 changed files with 835 additions and 3 deletions
--- 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

--- a/src/07-gbapp/testing-safety.md
+++ 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
--- 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

--- a/src/12-auth/security-checklist.md
+++ 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
--- a/src/12-auth/system-limits.md
+++ 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
--- 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