From 7ff1dc3bbae7e279deededa909aefe8cee806ca5 Mon Sep 17 00:00:00 2001 From: ronitchidara Date: Tue, 27 Jan 2026 20:20:10 +0530 Subject: [PATCH] compliance: add Phase 7 governance and procedure documentation Add SOC2/ISO 27001 compliance documentation suite: - incident-response.md: P1-P4 severity, 5-phase response, templates - access-control-policy.md: RBAC governance, provisioning/revocation - readiness-checklist.md: Self-assessment for all SOC2 TSC criteria - change-management.md: Standard/normal/emergency change workflows - vulnerability-disclosure.md: Safe harbor, reporting channels - security-metrics.md: KPIs, Prometheus alerts, Grafana dashboard - index.md: Navigation hub with control mapping Documents reference existing technical controls (audit-log.ts, rbac.ts) and provide practical audit log queries and alerting configurations. Co-Authored-By: Claude Opus 4.5 --- docs/compliance/access-control-policy.md | 330 ++++++++++++ docs/compliance/change-management.md | 480 ++++++++++++++++++ docs/compliance/incident-response.md | 398 +++++++++++++++ docs/compliance/index.md | 102 ++++ docs/compliance/readiness-checklist.md | 360 +++++++++++++ docs/compliance/security-metrics.md | 535 ++++++++++++++++++++ docs/compliance/vulnerability-disclosure.md | 230 +++++++++ docs/docs.json | 21 + 8 files changed, 2456 insertions(+) create mode 100644 docs/compliance/access-control-policy.md create mode 100644 docs/compliance/change-management.md create mode 100644 docs/compliance/incident-response.md create mode 100644 docs/compliance/index.md create mode 100644 docs/compliance/readiness-checklist.md create mode 100644 docs/compliance/security-metrics.md create mode 100644 docs/compliance/vulnerability-disclosure.md diff --git a/docs/compliance/access-control-policy.md b/docs/compliance/access-control-policy.md new file mode 100644 index 000000000..073f90276 --- /dev/null +++ b/docs/compliance/access-control-policy.md @@ -0,0 +1,330 @@ +--- +title: Access Control Policy +summary: User access management, RBAC governance, and authorization procedures for Clawdbot deployments. +permalink: /compliance/access-control-policy/ +--- + +# Access Control Policy + +This policy defines the principles, roles, and procedures for managing user access to Clawdbot systems. + +## Policy Statement + +Access to Clawdbot functionality shall be granted based on the principle of least privilege. Users receive only the permissions necessary to perform their authorized functions, and access is regularly reviewed and revoked when no longer needed. + +## Scope + +This policy applies to: +- Gateway API access +- Messaging channel interactions +- Command execution permissions +- Administrative functions +- Agent and tool access + +## Access Control Model + +Clawdbot implements Role-Based Access Control (RBAC) as defined in `src/security/rbac.ts`. + +### Built-in Roles + +| Role | Description | Permissions | Use Case | +|------|-------------|-------------|----------| +| `admin` | Full administrative access | All permissions | System administrators | +| `operator` | Operational access with approval rights | `exec`, `exec.approve` | Operations staff, power users | +| `user` | Standard execution access | `exec` | Regular users | +| `viewer` | Read-only access | `read-only` | Auditors, observers | + +### Permission Types + +| Permission | Description | Grants | +|------------|-------------|--------| +| `exec` | Execute basic commands | Shell commands, tool invocations | +| `exec.elevated` | Execute privileged commands | sudo, system administration | +| `exec.approve` | Approve pending executions | Approve requests from agents or other users | +| `admin` | Full administrative access | All permissions including RBAC management | +| `read-only` | View-only access | Read operations, no tool execution | + +### Permission Hierarchy + +``` +admin + └── exec.elevated + └── exec.approve + └── exec + └── read-only +``` + +The `admin` permission implicitly grants all other permissions. + +## Authentication Methods + +### Gateway Authentication + +| Method | Security Level | Use Case | Configuration | +|--------|---------------|----------|---------------| +| Token | High | API clients, automation | `gateway.auth.mode: token` | +| Password | Medium | Interactive users | `gateway.auth.mode: password` | +| Tailscale | High | Zero-trust networking | `gateway.tailscale.mode: serve` | +| Device Token | High | Paired devices | Automatic after pairing approval | + +**Token Requirements:** +- Minimum 24 characters +- Generated with cryptographic randomness +- Stored securely (environment variable or secrets manager) + +```bash +# Generate compliant token +openssl rand -base64 32 +``` + +### Channel Authentication + +Messaging channel access is controlled via: + +1. **Pairing codes**: 16-character codes with 80-bit entropy for initial authorization +2. **Allowlists**: Per-channel lists of authorized sender IDs +3. **Rate limiting**: 10 pairing attempts per minute maximum + +## Access Provisioning + +### New User Access Request + +1. **Request submission**: User submits access request specifying: + - Required role + - Business justification + - Channels needed + - Duration (if temporary) + +2. **Approval**: Security team or designated approver reviews request + +3. **Provisioning**: Administrator configures access: + +```yaml +# config.yaml +rbac: + enabled: true + assignments: + "user@example.com": operator # Assign role by user ID + "team-channel-id": user # Assign role by channel/group +``` + +4. **Verification**: User confirms access works as expected + +5. **Documentation**: Access grant recorded in access log + +### Role Assignment via CLI + +```bash +# Assign user to role +clawdbot config set rbac.assignments.USER_ID "role_name" + +# Verify assignment +clawdbot config get rbac.assignments.USER_ID +``` + +### Channel Authorization via Pairing + +```bash +# Initiate pairing (user sends from their device) +# Bot responds with pairing code + +# Administrator approves pairing +clawdbot pairing approve --code PAIRING_CODE + +# Or add directly to allowlist +clawdbot config set channels.telegram.dm.allowFrom '["user_id_1", "user_id_2"]' +``` + +## Access Review and Revocation + +### Periodic Access Review + +Conduct access reviews: +- **Admin role**: Quarterly +- **Operator role**: Semi-annually +- **User role**: Annually +- **All roles**: Upon role change or termination + +**Review checklist:** +- [ ] User still requires access +- [ ] Role is appropriate for current responsibilities +- [ ] No excessive permissions +- [ ] Last access date within expected timeframe + +### Access Revocation + +**Immediate revocation triggers:** +- Employment termination +- Role change removing need +- Security incident +- Policy violation + +**Revocation procedure:** + +```bash +# Remove RBAC assignment +clawdbot config unset rbac.assignments.USER_ID + +# Revoke channel pairing +clawdbot pairing revoke --channel CHANNEL --sender USER_ID + +# Revoke device pairing +clawdbot pairing revoke --device-id DEVICE_ID + +# Rotate gateway token if shared +clawdbot config set gateway.auth.token "$(openssl rand -base64 32)" +``` + +### Emergency Access Revocation + +For P1/P2 security incidents: + +```bash +# Disable all channel access temporarily +clawdbot config set channels.defaults.dmPolicy "disabled" + +# Rotate gateway authentication +clawdbot config set gateway.auth.token "$(openssl rand -base64 32)" + +# Restart gateway to terminate active sessions +clawdbot gateway stop && clawdbot gateway run +``` + +## Tool and Agent Restrictions + +### Tool Access Control + +Restrict tools per role: + +```yaml +rbac: + roles: + restricted_user: + name: "Restricted User" + permissions: [exec] + tools: + allow: + - read + - search + - glob + deny: + - bash + - write + - edit +``` + +### Agent Access Control + +Restrict agents per role: + +```yaml +rbac: + roles: + limited_agent_access: + name: "Limited Agent Access" + permissions: [exec] + agents: + - main + - support + # User cannot access other agents +``` + +## Audit and Logging + +### Access Events Logged + +All access-related events are logged to `~/.clawdbot/audit.jsonl`: + +| Event Type | Description | Data Captured | +|------------|-------------|---------------| +| `auth.login` | Successful authentication | Actor, method, timestamp | +| `auth.failure` | Failed authentication | Actor, reason, IP address | +| `rbac.denied` | Permission denied | Actor, action, resource, reason | +| `pairing.request` | Pairing initiated | Channel, sender | +| `pairing.approve` | Pairing approved | Actor, target device | +| `pairing.reject` | Pairing denied | Actor, target, reason | +| `pairing.revoke` | Access revoked | Actor, target device | + +### Audit Log Queries + +```bash +# Authentication failures in last 24 hours +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "auth.failure" and .ts > (now - 86400 | todate))' + +# All RBAC denials for a user +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "rbac.denied" and .actor.id == "USER_ID")' + +# Pairing activity summary +cat ~/.clawdbot/audit.jsonl | jq 'select(.type | startswith("pairing."))' +``` + +## Rate Limiting + +Protection against brute-force attacks: + +| Scope | Limit | Window | Action | +|-------|-------|--------|--------| +| Unauthenticated requests | 60 | 1 minute | Block | +| Channel messages | 200 | 1 minute | Queue | +| Pairing attempts | 10 | 1 minute | Reject | +| Auth failures | 5 | 5 minutes | Exponential backoff | + +Rate limit status is auditable via Prometheus metrics. + +## Compliance Verification + +### Security Audit Checks + +The `clawdbot security audit` command verifies: + +- RBAC is enabled for production deployments +- Gateway authentication is configured +- No wildcard allowlists (`*`) +- File permissions are restrictive +- Rate limiting is active + +```bash +# Run access control audit +clawdbot security audit --deep | grep -E "(rbac|auth|pairing)" +``` + +### Access Control Checklist + +- [ ] RBAC is enabled (`rbac.enabled: true`) +- [ ] Default role is appropriate (`rbac.defaultRole`) +- [ ] Admin role assignments are documented +- [ ] Gateway authentication is enabled +- [ ] Channel allowlists are explicit (no wildcards) +- [ ] Pairing rate limiting is active +- [ ] Audit logging is enabled +- [ ] Access reviews are scheduled + +## Exceptions + +Access control exceptions require: +- Written justification +- Security team approval +- Defined expiration date +- Compensating controls documented +- Periodic review + +## Policy Violations + +Violations of this policy may result in: +- Immediate access revocation +- Security incident classification +- Escalation per incident response procedure + +## Related Documentation + +- [Security Hardening Guide](/enterprise/security-hardening#role-based-access-control-rbac) - RBAC configuration details +- [Gateway Authentication](/gateway/authentication) - Authentication setup +- [Pairing Guide](/start/pairing) - Device pairing procedures +- [Incident Response](/compliance/incident-response) - Handling access-related incidents + +--- + +*Policy owner: Security Team* +*Effective date: 2026-01-27* +*Last reviewed: 2026-01-27* +*Next review: 2026-07-27* diff --git a/docs/compliance/change-management.md b/docs/compliance/change-management.md new file mode 100644 index 000000000..dba7a5cf2 --- /dev/null +++ b/docs/compliance/change-management.md @@ -0,0 +1,480 @@ +--- +title: Change Management Procedure +summary: Procedures for managing configuration, version, and operational changes in Clawdbot deployments. +permalink: /compliance/change-management/ +--- + +# Change Management Procedure + +This document defines procedures for managing changes to Clawdbot configuration, versions, channels, and plugins in a controlled manner. + +## Purpose + +Ensure all changes to Clawdbot systems are: +- Authorized before implementation +- Tested appropriately +- Documented with audit trail +- Reversible if issues arise + +## Scope + +This procedure covers: +- Configuration changes (settings, credentials, policies) +- Version upgrades (Clawdbot releases) +- Channel modifications (adding, removing, reconfiguring) +- Plugin management (installation, updates, removal) +- Infrastructure changes (gateway, networking) + +## Change Categories + +### Standard Changes + +Pre-approved, low-risk changes with established procedures. + +| Change Type | Examples | Approval | Testing | +|-------------|----------|----------|---------| +| User access | RBAC assignment, pairing approval | Self-service | None required | +| Agent config | System prompt updates, model selection | Self-service | Functional test | +| Logging | Log level changes | Self-service | None required | + +### Normal Changes + +Planned changes requiring approval and testing. + +| Change Type | Examples | Approval | Testing | +|-------------|----------|----------|---------| +| Version upgrade | Minor/patch releases | Change owner | Staging verification | +| Channel addition | New messaging platform | Security review | Integration test | +| Plugin installation | New extension | Security review | Compatibility test | +| Security config | Auth mode, RBAC roles | Security team | Security audit | + +### Emergency Changes + +Urgent changes to address incidents or critical vulnerabilities. + +| Change Type | Examples | Approval | Testing | +|-------------|----------|----------|---------| +| Security patch | Critical vulnerability fix | Verbal, documented post-hoc | Smoke test only | +| Incident response | Credential rotation, access revocation | Incident commander | Verification only | +| Service restoration | Gateway restart, config rollback | On-call engineer | Health check | + +## Change Process + +### Standard Change Workflow + +``` +Request → Implement → Verify → Document +``` + +1. **Implement** the change +2. **Verify** using established procedure +3. **Document** in change log (audit trail automatic) + +### Normal Change Workflow + +``` +Request → Review → Approve → Test → Implement → Verify → Document +``` + +1. **Request**: Submit change request with: + - Description of change + - Business justification + - Risk assessment + - Rollback plan + - Testing plan + +2. **Review**: Designated reviewer assesses: + - Completeness of request + - Risk level appropriate + - Rollback plan viable + +3. **Approve**: Approver authorizes change + +4. **Test**: Execute testing plan: + - Staging environment (if available) + - Security audit pre-check + +5. **Implement**: Apply change + +6. **Verify**: Confirm success: + - Functional verification + - Security audit post-check + - Health check + +7. **Document**: Record in change log + +### Emergency Change Workflow + +``` +Assess → Approve (verbal) → Implement → Verify → Document (post-hoc) +``` + +1. **Assess**: Confirm emergency criteria met +2. **Approve**: Verbal approval from authorized person +3. **Implement**: Apply minimal change to address issue +4. **Verify**: Confirm issue resolved +5. **Document**: Complete change record within 24 hours + +## Change Implementation Procedures + +### Configuration Changes + +All configuration changes are logged to the audit trail automatically. + +**Pre-change checklist:** +- [ ] Current config backed up +- [ ] Change command prepared +- [ ] Rollback command prepared +- [ ] Verification steps defined + +**Implementation:** +```bash +# Backup current configuration +clawdbot config show > config-backup-$(date +%Y%m%d-%H%M%S).yaml + +# Apply configuration change +clawdbot config set KEY VALUE + +# Verify change applied +clawdbot config get KEY + +# Run security audit to verify no new issues +clawdbot security audit --deep +``` + +**Audit trail:** +Configuration changes emit `config.change` audit events: +```json +{ + "ts": "2026-01-27T10:30:00.000Z", + "type": "config.change", + "actor": { "type": "user", "id": "admin" }, + "outcome": "success", + "metadata": { + "changes": { "rbac.enabled": true } + } +} +``` + +### Version Upgrades + +**Pre-upgrade checklist:** +- [ ] Current version documented +- [ ] Release notes reviewed +- [ ] Breaking changes identified +- [ ] Backup completed +- [ ] Rollback procedure prepared + +**Implementation:** +```bash +# Document current version +clawdbot --version > version-before.txt + +# Stop gateway gracefully +clawdbot gateway stop + +# Backup state directory +cp -r ~/.clawdbot ~/.clawdbot-backup-$(date +%Y%m%d) + +# Update Clawdbot +clawdbot update +# or: npm update -g clawdbot + +# Verify new version +clawdbot --version + +# Start gateway +clawdbot gateway run + +# Verify health +clawdbot status --all +clawdbot security audit --deep +``` + +**Rollback (if needed):** +```bash +# Stop gateway +clawdbot gateway stop + +# Restore previous version +npm install -g clawdbot@PREVIOUS_VERSION + +# Restore state if needed +rm -rf ~/.clawdbot +cp -r ~/.clawdbot-backup-YYYYMMDD ~/.clawdbot + +# Restart +clawdbot gateway run +``` + +### Channel Changes + +**Adding a new channel:** + +1. **Security review**: Assess channel-specific risks +2. **Configuration**: +```bash +# Configure channel credentials +clawdbot config set channels.CHANNEL.token "BOT_TOKEN" +clawdbot config set channels.CHANNEL.enabled true + +# Configure access policy +clawdbot config set channels.CHANNEL.dm.policy "pairing" +``` +3. **Verification**: +```bash +# Check channel status +clawdbot channels status --channel CHANNEL + +# Run security audit +clawdbot security audit --deep | grep CHANNEL +``` + +**Removing a channel:** +```bash +# Disable channel +clawdbot config set channels.CHANNEL.enabled false + +# Revoke any pairings +clawdbot pairing list --channel CHANNEL +clawdbot pairing revoke --channel CHANNEL --all + +# Remove credentials (optional) +clawdbot config unset channels.CHANNEL.token + +# Restart gateway +clawdbot gateway stop && clawdbot gateway run +``` + +### Plugin Changes + +**Installing a plugin:** + +1. **Security review**: Verify plugin source and permissions +2. **Installation**: +```bash +# Install plugin +clawdbot plugins install PLUGIN_NAME + +# Verify installation +clawdbot plugins list + +# Configure plugin +clawdbot config set plugins.PLUGIN_NAME.enabled true +``` +3. **Verification**: +```bash +# Test plugin functionality +clawdbot plugins test PLUGIN_NAME + +# Security audit +clawdbot security audit --deep +``` + +**Updating a plugin:** +```bash +# Update specific plugin +clawdbot plugins update PLUGIN_NAME + +# Or update all plugins +clawdbot plugins update --all + +# Verify +clawdbot plugins list +``` + +**Removing a plugin:** +```bash +# Disable plugin +clawdbot config set plugins.PLUGIN_NAME.enabled false + +# Uninstall +clawdbot plugins uninstall PLUGIN_NAME + +# Verify removal +clawdbot plugins list +``` + +### RBAC Changes + +**Adding a new role:** +```yaml +# config.yaml addition +rbac: + roles: + new_role: + name: "New Role Name" + description: "Purpose of this role" + permissions: + - exec + tools: + deny: + - bash +``` + +```bash +# Apply via CLI +clawdbot config set rbac.roles.new_role.name "New Role Name" +clawdbot config set rbac.roles.new_role.permissions '["exec"]' + +# Verify +clawdbot config get rbac.roles.new_role +``` + +**Modifying role permissions:** +```bash +# Backup current role config +clawdbot config get rbac.roles.ROLE > role-backup.yaml + +# Update permissions +clawdbot config set rbac.roles.ROLE.permissions '["exec", "exec.approve"]' + +# Verify no unintended access +clawdbot security audit --deep | grep rbac +``` + +## Risk Assessment + +### Risk Categories + +| Risk Level | Criteria | Examples | +|------------|----------|----------| +| High | Security impact, data exposure | Auth changes, RBAC modifications, channel credentials | +| Medium | Service disruption potential | Version upgrades, plugin changes | +| Low | Minimal impact | Log levels, cosmetic changes | + +### Risk Mitigation + +| Risk Level | Required Controls | +|------------|-------------------| +| High | Security team approval, staging test, documented rollback | +| Medium | Change owner approval, basic testing, rollback plan | +| Low | Self-service, verification | + +## Testing Requirements + +### Test Types by Change Category + +| Change Type | Unit Test | Integration Test | Security Audit | Staging | +|-------------|-----------|------------------|----------------|---------| +| Standard | - | - | - | - | +| Normal (Low) | - | Verify | Post-change | - | +| Normal (Medium) | - | Functional | Pre/Post | Optional | +| Normal (High) | If applicable | Full | Pre/Post | Required | +| Emergency | - | Smoke | Post-change | - | + +### Security Audit Verification + +Run before and after high-risk changes: + +```bash +# Pre-change baseline +clawdbot security audit --deep > audit-pre-$(date +%Y%m%d-%H%M%S).txt + +# [Apply change] + +# Post-change verification +clawdbot security audit --deep > audit-post-$(date +%Y%m%d-%H%M%S).txt + +# Compare findings +diff audit-pre-*.txt audit-post-*.txt +``` + +## Documentation Requirements + +### Change Record Template + +```markdown +# Change Record: CHG-YYYY-NNN + +## Summary +- **Type**: Standard/Normal/Emergency +- **Risk Level**: Low/Medium/High +- **Status**: Requested/Approved/Implemented/Verified/Closed +- **Requested**: YYYY-MM-DD +- **Implemented**: YYYY-MM-DD + +## Description +[What is being changed and why] + +## Business Justification +[Why this change is needed] + +## Risk Assessment +- **Impact if change fails**: [Description] +- **Likelihood of failure**: Low/Medium/High +- **Mitigation**: [Rollback plan] + +## Testing Plan +1. [Test step 1] +2. [Test step 2] + +## Implementation Steps +1. [Step 1] +2. [Step 2] + +## Rollback Plan +1. [Rollback step 1] +2. [Rollback step 2] + +## Verification +- [ ] Change applied successfully +- [ ] Functionality verified +- [ ] Security audit passed +- [ ] No unexpected side effects + +## Approvals +| Role | Name | Date | +|------|------|------| +| Requester | [Name] | YYYY-MM-DD | +| Approver | [Name] | YYYY-MM-DD | +| Implementer | [Name] | YYYY-MM-DD | + +## Post-Implementation Notes +[Any observations or follow-up actions] +``` + +### Audit Trail + +All changes are automatically logged: + +```bash +# View recent config changes +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "config.change")' | tail -10 + +# View changes by actor +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "config.change" and .actor.id == "ACTOR_ID")' + +# View changes in time range +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "config.change" and .ts >= "2026-01-01" and .ts <= "2026-01-31")' +``` + +## Roles and Responsibilities + +| Role | Responsibilities | +|------|------------------| +| Change Requester | Submit request, provide justification, execute standard changes | +| Change Approver | Review requests, approve/reject, ensure compliance | +| Change Implementer | Execute approved changes, verify success | +| Security Team | Review high-risk changes, maintain procedures | +| On-call Engineer | Handle emergency changes, escalate as needed | + +## Compliance + +This procedure supports: +- **SOC2 CC8.1**: Change management for system components +- **ISO 27001 A.12.1.2**: Change management +- **ISO 27001 A.14.2.2**: System change control procedures + +## Related Documentation + +- [Security Hardening](/enterprise/security-hardening) - Security configuration +- [Incident Response](/compliance/incident-response) - Emergency procedures +- [Access Control Policy](/compliance/access-control-policy) - Authorization for changes +- [Gateway Configuration](/gateway/configuration) - Configuration reference + +--- + +*Procedure owner: Operations Team* +*Last reviewed: 2026-01-27* +*Next review: 2026-07-27* diff --git a/docs/compliance/incident-response.md b/docs/compliance/incident-response.md new file mode 100644 index 000000000..a593b2659 --- /dev/null +++ b/docs/compliance/incident-response.md @@ -0,0 +1,398 @@ +--- +title: Incident Response Procedure +summary: Security incident detection, classification, response, and recovery procedures for Clawdbot deployments. +permalink: /compliance/incident-response/ +--- + +# Incident Response Procedure + +This document defines the procedures for detecting, classifying, responding to, and recovering from security incidents in Clawdbot deployments. + +## Scope + +This procedure applies to: +- Unauthorized access attempts to the Clawdbot gateway +- Compromise of messaging channel credentials +- Malicious command execution via connected channels +- Data exfiltration or unauthorized data access +- Denial of service attacks against the gateway +- Prompt injection attacks that bypass controls + +## Incident Classification + +### Severity Levels + +| Severity | Code | Description | Response Time | Examples | +|----------|------|-------------|---------------|----------| +| Critical | P1 | Active compromise or data breach | Immediate (15 min) | Credential theft, unauthorized admin access, active data exfiltration | +| High | P2 | Attempted compromise or security control failure | 1 hour | Repeated auth failures from unknown sources, RBAC bypass, successful prompt injection | +| Medium | P3 | Policy violation or anomalous behavior | 4 hours | Elevated exec usage outside normal hours, unusual channel activity patterns | +| Low | P4 | Security event requiring review | 24 hours | Failed pairing attempts, rate limit triggers, configuration warnings | + +### Classification Criteria + +Use these indicators to classify incidents: + +**P1 (Critical)** +- Evidence of successful unauthorized access +- Credentials confirmed compromised +- Active malicious command execution +- Data confirmed exfiltrated +- Gateway integrity compromised + +**P2 (High)** +- Multiple failed authentication attempts from single source +- Blocked malicious commands attempted +- Prompt injection detected with high confidence +- Security control bypassed but no confirmed impact +- Unauthorized configuration changes attempted + +**P3 (Medium)** +- Single failed authentication from unknown source +- Elevated command execution outside policy +- Rate limit exceeded repeatedly +- Security audit findings unresolved + +**P4 (Low)** +- Pairing request from unknown device +- Informational security warnings +- Minor policy deviations + +## Detection + +### Audit Log Monitoring + +Security events are logged to `~/.clawdbot/audit.jsonl`. Monitor these event types: + +| Event Type | Severity Indicator | Description | +|------------|-------------------|-------------| +| `auth.failure` | P2/P3 | Failed authentication attempt | +| `rbac.denied` | P3 | Permission check failed | +| `exec.reject` | P3 | Command blocked by policy | +| `pairing.reject` | P4 | Pairing request denied | +| `config.change` | P3/P4 | Configuration modified | + +**Detection Query Examples** + +```bash +# Find failed authentication attempts in last hour +cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "auth.failure" and .ts > (now - 3600 | todate))' + +# Find RBAC denials by actor +cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "rbac.denied")' | jq -s 'group_by(.actor.id) | map({actor: .[0].actor.id, count: length})' + +# Find command rejections +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "exec.reject")' + +# Correlate events by trace ID +cat ~/.clawdbot/audit.jsonl | jq 'select(.traceId == "TRACE_ID_HERE")' +``` + +### Prometheus Alerts + +Configure these alerts for automated detection (see [Observability Guide](/enterprise/observability#alerting)): + +```yaml +groups: + - name: clawdbot-security + rules: + # P2: High rate of authentication failures + - alert: HighAuthFailureRate + expr: increase(clawdbot_auth_failure_total[5m]) > 10 + for: 1m + labels: + severity: high + incident_type: auth_failure + annotations: + summary: "High authentication failure rate detected" + runbook: "Check audit logs for auth.failure events" + + # P2: RBAC denials spike + - alert: RbacDenialSpike + expr: increase(clawdbot_rbac_denied_total[5m]) > 5 + for: 1m + labels: + severity: high + incident_type: rbac_denial + annotations: + summary: "Unusual RBAC denial rate" + + # P3: Rate limiting activated + - alert: RateLimitExceeded + expr: clawdbot_rate_limit_exceeded_total > 0 + for: 5m + labels: + severity: medium + incident_type: rate_limit + annotations: + summary: "Rate limiting is actively blocking requests" +``` + +### Manual Detection Indicators + +Watch for these patterns: +- Unexpected gateway restarts +- New devices in pairing store +- Configuration file modifications +- Unusual message patterns in connected channels +- Performance degradation + +## Response Phases + +### Phase 1: Triage (P1: 15 min, P2: 30 min, P3: 2 hr, P4: 24 hr) + +**Objectives**: Confirm incident, assess scope, assign severity + +1. **Verify the alert** + ```bash + # Check recent audit events + tail -100 ~/.clawdbot/audit.jsonl | jq -c 'select(.outcome == "failure" or .outcome == "denied")' + + # Check gateway status + clawdbot status --all + + # Run security audit + clawdbot security audit --deep + ``` + +2. **Identify affected components** + - Which channels are involved? + - Which users/actors are affected? + - What data or functionality is at risk? + +3. **Assign severity** using classification criteria above + +4. **Document initial findings** in incident record (see template below) + +5. **Notify stakeholders** per escalation matrix + +### Phase 2: Containment (P1: 30 min, P2: 2 hr, P3: 8 hr) + +**Objectives**: Stop active threat, prevent further damage + +**Immediate containment actions by incident type:** + +**Unauthorized Access** +```bash +# Rotate gateway authentication token +clawdbot config set gateway.auth.token "$(openssl rand -base64 32)" + +# Restart gateway to force reconnection +clawdbot gateway stop && clawdbot gateway run + +# Revoke specific device pairing +clawdbot pairing revoke --device-id DEVICE_ID +``` + +**Compromised Channel Credentials** +```bash +# Disable affected channel +clawdbot config set channels.CHANNEL.enabled false + +# Rotate channel credentials +# (Provider-specific: regenerate bot token in provider dashboard) +clawdbot config set channels.CHANNEL.token "NEW_TOKEN" +``` + +**Malicious Command Execution** +```bash +# Enable strict approval mode +clawdbot config set approvals.exec.enabled true +clawdbot config set approvals.exec.requireApproval '["elevated","destructive"]' + +# Restrict user permissions via RBAC +clawdbot config set rbac.assignments.SENDER_ID "viewer" +``` + +**Prompt Injection Attack** +```bash +# Block specific sender +clawdbot pairing revoke --channel CHANNEL --sender SENDER_ID + +# Enable stricter input validation +clawdbot config set security.promptInjection.mode "strict" +``` + +### Phase 3: Eradication (P1: 2 hr, P2: 24 hr, P3: 72 hr) + +**Objectives**: Remove threat, identify root cause + +1. **Analyze attack vector** + ```bash + # Export relevant audit logs + cat ~/.clawdbot/audit.jsonl | jq 'select(.ts >= "START_TIME" and .ts <= "END_TIME")' > incident-logs.json + + # Trace full attack path using trace IDs + cat incident-logs.json | jq -s 'group_by(.traceId) | .[]' + ``` + +2. **Identify root cause** + - Misconfiguration? + - Credential exposure? + - Software vulnerability? + - Social engineering? + +3. **Remove malicious artifacts** + - Clear compromised sessions: `clawdbot session clear --agent AGENT_ID` + - Remove unauthorized pairings: `clawdbot pairing list && clawdbot pairing revoke` + - Reset modified configurations + +4. **Patch vulnerabilities** + - Update Clawdbot if applicable: `clawdbot update` + - Apply configuration hardening per security audit recommendations + +### Phase 4: Recovery (P1: 4 hr, P2: 48 hr, P3: 1 week) + +**Objectives**: Restore normal operations, verify security + +1. **Verify clean state** + ```bash + # Run full security audit + clawdbot security audit --deep + + # Verify no critical findings + clawdbot security audit --summary + ``` + +2. **Restore services gradually** + - Re-enable channels one at a time + - Monitor for anomalies after each restoration + - Verify authorized users can access + +3. **Confirm recovery** + - All channels operational + - Authentication working + - No security audit warnings + - Normal message processing + +4. **Update monitoring** + - Add new detection rules if needed + - Adjust alert thresholds based on incident + +### Phase 5: Post-Incident Review + +**Objectives**: Document lessons learned, improve procedures + +Conduct review within 5 business days of incident closure. + +**Review agenda:** +1. Incident timeline reconstruction +2. Detection effectiveness assessment +3. Response procedure evaluation +4. Root cause analysis +5. Improvement recommendations + +## Incident Record Template + +```markdown +# Incident Record: [INC-YYYY-NNN] + +## Summary +- **Severity**: P1/P2/P3/P4 +- **Status**: Open/Contained/Eradicated/Recovered/Closed +- **Detected**: YYYY-MM-DD HH:MM UTC +- **Resolved**: YYYY-MM-DD HH:MM UTC +- **Duration**: X hours + +## Description +[Brief description of the incident] + +## Impact +- **Users affected**: N +- **Channels affected**: [list] +- **Data impact**: None/Exposed/Exfiltrated +- **Service impact**: None/Degraded/Unavailable + +## Timeline +| Time (UTC) | Event | Actor | +|------------|-------|-------| +| HH:MM | Detection triggered | System | +| HH:MM | Triage started | [Name] | +| HH:MM | Containment action taken | [Name] | +| HH:MM | Root cause identified | [Name] | +| HH:MM | Recovery complete | [Name] | + +## Root Cause +[Description of what caused the incident] + +## Actions Taken +1. [Containment action] +2. [Eradication action] +3. [Recovery action] + +## Evidence +- Audit logs: [location] +- Screenshots: [location] +- Configuration snapshots: [location] + +## Lessons Learned +[What worked, what did not, what to improve] + +## Follow-up Actions +| Action | Owner | Due Date | Status | +|--------|-------|----------|--------| +| [Action item] | [Name] | YYYY-MM-DD | Open | +``` + +## Escalation Matrix + +| Severity | Primary Contact | Secondary Contact | Executive Notification | +|----------|-----------------|-------------------|------------------------| +| P1 | On-call engineer | Security lead | Yes (within 1 hour) | +| P2 | On-call engineer | Security lead | Yes (within 4 hours) | +| P3 | Security team | - | No | +| P4 | Security team | - | No | + +## Communication Templates + +### Internal Notification (P1/P2) + +``` +Subject: [SECURITY INCIDENT] P[N] - [Brief description] + +A security incident has been detected in the Clawdbot deployment. + +Severity: P[N] +Status: [Triage/Containment/Eradication/Recovery] +Detected: [timestamp] + +Impact: +- [Summary of impact] + +Current Actions: +- [What is being done] + +Next Update: [timestamp] + +Incident Commander: [name] +``` + +### Status Update + +``` +Subject: [UPDATE] [INC-YYYY-NNN] - [Brief description] + +Status: [Current status] +Update Time: [timestamp] + +Progress since last update: +- [Actions completed] + +Current focus: +- [What is being worked on] + +Next update: [timestamp] +``` + +## Related Documentation + +- [Threat Model](/security/threat-model) - Attack surface and mitigations +- [Security Hardening](/enterprise/security-hardening) - Security configuration +- [Observability Guide](/enterprise/observability) - Monitoring setup +- [Security Metrics](/compliance/security-metrics) - Incident KPIs + +--- + +*Procedure owner: Security Team* +*Last reviewed: 2026-01-27* +*Next review: 2026-07-27* diff --git a/docs/compliance/index.md b/docs/compliance/index.md new file mode 100644 index 000000000..4c9b3de0b --- /dev/null +++ b/docs/compliance/index.md @@ -0,0 +1,102 @@ +--- +title: Compliance Overview +summary: SOC2 and ISO 27001 compliance documentation and readiness resources for Clawdbot deployments. +permalink: /compliance/ +--- + +# Compliance Overview + +This section provides governance and procedure documentation to support SOC2 Type II and ISO 27001 compliance for Clawdbot enterprise deployments. + +## Technical Controls Foundation + +Clawdbot includes built-in security controls that form the technical foundation for compliance: + +| Control | Implementation | Documentation | +|---------|---------------|---------------| +| Audit logging | `~/.clawdbot/audit.jsonl` with 7-day retention | [Security Hardening](/enterprise/security-hardening#audit-logging) | +| Role-based access control | 4 built-in roles with granular permissions | [RBAC Guide](/enterprise/security-hardening#role-based-access-control-rbac) | +| Authentication | Token, password, and Tailscale modes | [Gateway Authentication](/gateway/authentication) | +| Rate limiting | Token bucket with per-client tracking | [Rate Limiting](/enterprise/security-hardening#rate-limiting) | +| Security audit CLI | Automated checks for misconfigurations | [Security Audit](/cli/security) | + +## Compliance Documents + +### Policies and Procedures + +| Document | Purpose | SOC2 Mapping | ISO 27001 Mapping | +|----------|---------|--------------|-------------------| +| [Incident Response](/compliance/incident-response) | Security incident detection, triage, and recovery | CC7.2, CC7.3, CC7.4 | A.16.1 | +| [Access Control Policy](/compliance/access-control-policy) | User access management and RBAC governance | CC6.1, CC6.2, CC6.3 | A.9.1, A.9.2, A.9.4 | +| [Change Management](/compliance/change-management) | Configuration and version change procedures | CC8.1 | A.12.1, A.14.2 | +| [Vulnerability Disclosure](/compliance/vulnerability-disclosure) | Responsible disclosure and security reporting | CC7.1 | A.12.6 | + +### Measurement and Readiness + +| Document | Purpose | SOC2 Mapping | ISO 27001 Mapping | +|----------|---------|--------------|-------------------| +| [Security Metrics](/compliance/security-metrics) | KPIs and continuous monitoring guidance | CC4.1, CC4.2 | A.18.2 | +| [Readiness Checklist](/compliance/readiness-checklist) | Self-assessment for audit preparation | All TSC | Clause 9, 10 | + +## SOC2 Trust Services Criteria Coverage + +| Category | Criteria | Primary Documents | +|----------|----------|-------------------| +| CC1: Control Environment | Governance and oversight | Readiness Checklist | +| CC2: Communication | Internal security communication | Incident Response | +| CC3: Risk Assessment | Risk identification | [Threat Model](/security/threat-model) | +| CC4: Monitoring | Ongoing monitoring activities | Security Metrics | +| CC5: Control Activities | Policy implementation | Access Control Policy | +| CC6: Logical Access | Access management | Access Control Policy | +| CC7: System Operations | Incident management | Incident Response, Vulnerability Disclosure | +| CC8: Change Management | Change control | Change Management | +| CC9: Risk Mitigation | Recovery planning | Incident Response | + +## ISO 27001 Annex A Coverage + +| Control Domain | Controls | Primary Documents | +|----------------|----------|-------------------| +| A.9 Access Control | A.9.1-A.9.4 | Access Control Policy | +| A.12 Operations Security | A.12.1, A.12.6 | Change Management, Vulnerability Disclosure | +| A.14 System Acquisition | A.14.2 | Change Management | +| A.16 Incident Management | A.16.1 | Incident Response | +| A.18 Compliance | A.18.2 | Security Metrics, Readiness Checklist | + +## Related Documentation + +- [Threat Model](/security/threat-model) - Security threat analysis and mitigations +- [Data Handling Policy](/security/data-handling) - Data storage, retention, and privacy +- [Security Hardening Guide](/enterprise/security-hardening) - Technical security configuration +- [Observability Guide](/enterprise/observability) - Metrics and monitoring setup + +## Automated Compliance Verification + +Run the security audit to verify compliance controls: + +```bash +# Full security audit with deep gateway probe +clawdbot security audit --deep + +# Summary of findings by severity +clawdbot security audit --summary +``` + +The audit checks: +- Gateway authentication configuration +- RBAC policy effectiveness +- File permission hardening +- Channel security policies +- Rate limiting status +- Audit logging enablement + +## Getting Started + +1. **Assess current state**: Run `clawdbot security audit --deep` to identify gaps +2. **Review policies**: Read each compliance document and adapt to your organization +3. **Implement controls**: Configure RBAC, audit logging, and authentication per guidelines +4. **Collect evidence**: Use the Readiness Checklist to gather audit artifacts +5. **Monitor continuously**: Set up Security Metrics dashboards for ongoing compliance + +--- + +*Last updated: 2026-01-27* diff --git a/docs/compliance/readiness-checklist.md b/docs/compliance/readiness-checklist.md new file mode 100644 index 000000000..02d8a2a27 --- /dev/null +++ b/docs/compliance/readiness-checklist.md @@ -0,0 +1,360 @@ +--- +title: Compliance Readiness Checklist +summary: Self-assessment checklist for SOC2 Type II and ISO 27001 compliance readiness. +permalink: /compliance/readiness-checklist/ +--- + +# Compliance Readiness Checklist + +This checklist helps assess readiness for SOC2 Type II and ISO 27001 compliance audits. Use it to identify gaps and collect evidence. + +## How to Use This Checklist + +1. **Run automated checks**: `clawdbot security audit --deep` +2. **Review each section**: Verify controls are implemented +3. **Collect evidence**: Document artifacts for each control +4. **Track remediation**: Address any gaps identified +5. **Schedule reviews**: Re-assess quarterly + +## SOC2 Trust Services Criteria + +### CC1: Control Environment + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC1.1 | Security policies documented | Review `/compliance/*` docs exist | Policy documents | +| CC1.2 | Roles and responsibilities defined | Check RBAC config | `clawdbot config get rbac` | +| CC1.3 | Security training provided | N/A (organizational) | Training records | +| CC1.4 | Competence evaluated | N/A (organizational) | Performance records | + +**Automated Check:** +```bash +# Verify RBAC is enabled and configured +clawdbot config get rbac.enabled +clawdbot config get rbac.roles +``` + +### CC2: Communication and Information + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC2.1 | Security policies communicated | Policies accessible | Documentation links | +| CC2.2 | External party communications | Disclosure policy exists | [Vulnerability Disclosure](/compliance/vulnerability-disclosure) | +| CC2.3 | Incident communication | Incident response documented | [Incident Response](/compliance/incident-response) | + +### CC3: Risk Assessment + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC3.1 | Risk objectives defined | Threat model documented | [Threat Model](/security/threat-model) | +| CC3.2 | Risk identification | Security audit identifies risks | `clawdbot security audit --deep` | +| CC3.3 | Fraud risk considered | Prompt injection risks documented | Threat model attack vectors | +| CC3.4 | Change risk assessed | Change management documented | [Change Management](/compliance/change-management) | + +**Automated Check:** +```bash +# Run full security audit +clawdbot security audit --deep + +# Check for critical findings +clawdbot security audit --summary +``` + +### CC4: Monitoring Activities + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC4.1 | Ongoing monitoring | Audit logging enabled | Check audit.jsonl exists | +| CC4.2 | Control effectiveness evaluated | Security metrics tracked | [Security Metrics](/compliance/security-metrics) | + +**Automated Check:** +```bash +# Verify audit logging is working +ls -la ~/.clawdbot/audit.jsonl + +# Check recent audit events +tail -10 ~/.clawdbot/audit.jsonl | jq .type + +# Verify Prometheus metrics available (if configured) +curl -s http://localhost:18789/metrics | head -20 +``` + +### CC5: Control Activities + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC5.1 | Controls mitigate risks | Security controls documented | Security hardening guide | +| CC5.2 | Technology controls | Automated checks implemented | Security audit CLI | +| CC5.3 | Policies deployed | Configuration enforces policy | Config validation | + +### CC6: Logical and Physical Access + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC6.1 | Access rights defined | RBAC roles documented | [Access Control Policy](/compliance/access-control-policy) | +| CC6.2 | Access provisioned | Assignment process defined | Access policy procedures | +| CC6.3 | Access removed | Revocation process defined | Access policy procedures | +| CC6.4 | Access reviewed | Review schedule exists | Quarterly review records | +| CC6.5 | Physical access | N/A (software system) | - | +| CC6.6 | Authentication mechanisms | Token/password/Tailscale configured | Gateway auth config | +| CC6.7 | Access credentials managed | Token rotation guidance | Security hardening guide | +| CC6.8 | Transmission protected | Rate limiting implemented | Rate limit config | + +**Automated Check:** +```bash +# Verify authentication is configured +clawdbot security audit --deep | grep -i "auth" + +# Check RBAC is enabled +clawdbot config get rbac.enabled + +# Verify no wildcard allowlists +clawdbot security audit --deep | grep -i "wildcard" +``` + +### CC7: System Operations + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC7.1 | Vulnerabilities detected | Security audit runs | Audit output | +| CC7.2 | Anomalies monitored | Alerting configured | Prometheus alerts | +| CC7.3 | Incidents evaluated | Incident response defined | [Incident Response](/compliance/incident-response) | +| CC7.4 | Incidents responded to | Response procedures exist | Incident response phases | +| CC7.5 | Recovery activities | Recovery procedures exist | Incident response Phase 4 | + +**Automated Check:** +```bash +# Run vulnerability scan +clawdbot security audit --deep + +# Check for security findings +clawdbot security audit --summary +``` + +### CC8: Change Management + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC8.1 | Changes authorized | Change process documented | [Change Management](/compliance/change-management) | + +**Automated Check:** +```bash +# Check config change audit events +cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "config.change")' | tail -5 +``` + +### CC9: Risk Mitigation + +| Req | Control | Verification | Evidence | +|-----|---------|--------------|----------| +| CC9.1 | Risk mitigation | Controls reduce risk | Threat model mitigations | +| CC9.2 | Vendor risk | Provider risks documented | Data handling policy | + +## ISO 27001 Annex A Controls + +### A.5: Information Security Policies + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.5.1.1 | Policies for information security | Compliance documentation suite | +| A.5.1.2 | Review of policies | Review dates on policy documents | + +### A.6: Organization of Information Security + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.6.1.1 | Information security roles | RBAC role definitions | +| A.6.1.2 | Segregation of duties | Role separation (admin vs user) | + +### A.9: Access Control + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.9.1.1 | Access control policy | [Access Control Policy](/compliance/access-control-policy) | +| A.9.1.2 | Access to networks | Gateway bind configuration | +| A.9.2.1 | User registration | Pairing procedures | +| A.9.2.2 | Access provisioning | Role assignment procedures | +| A.9.2.3 | Privileged access | Admin/operator role restrictions | +| A.9.2.4 | Secret authentication | Token generation guidance | +| A.9.2.5 | Access rights review | Quarterly review schedule | +| A.9.2.6 | Access removal | Revocation procedures | +| A.9.4.1 | Access restriction | RBAC permission checks | +| A.9.4.2 | Secure log-on | Rate limiting, exponential backoff | +| A.9.4.3 | Password management | Token/password requirements | + +**Automated Check:** +```bash +# Full access control verification +clawdbot security audit --deep | grep -E "(rbac|auth|pairing|allowlist)" +``` + +### A.12: Operations Security + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.12.1.1 | Documented procedures | CLI documentation | +| A.12.1.2 | Change management | [Change Management](/compliance/change-management) | +| A.12.1.4 | Separation of environments | Config isolation per agent | +| A.12.4.1 | Event logging | Audit log implementation | +| A.12.4.2 | Protection of logs | File permissions (0o600) | +| A.12.4.3 | Admin/operator logs | Auth events logged | +| A.12.6.1 | Technical vulnerabilities | Security audit CLI | + +### A.14: System Development + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.14.2.2 | Change control | Change management procedures | +| A.14.2.3 | Technical review | Security audit after changes | + +### A.16: Incident Management + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.16.1.1 | Responsibilities defined | Incident response roles | +| A.16.1.2 | Reporting events | Detection procedures | +| A.16.1.3 | Reporting weaknesses | Vulnerability disclosure | +| A.16.1.4 | Assessment of events | Severity classification | +| A.16.1.5 | Response to incidents | Response phases | +| A.16.1.6 | Learning from incidents | Post-incident review | +| A.16.1.7 | Collection of evidence | Evidence collection guidance | + +### A.18: Compliance + +| Control | Requirement | Evidence | +|---------|-------------|----------| +| A.18.2.2 | Compliance with policies | Security audit verification | +| A.18.2.3 | Technical compliance | Automated compliance checks | + +## Evidence Collection Guide + +### Automated Evidence + +| Evidence Type | Collection Method | Frequency | +|--------------|-------------------|-----------| +| Security audit report | `clawdbot security audit --deep > audit-$(date +%Y%m%d).txt` | Weekly | +| Configuration snapshot | `clawdbot config show > config-$(date +%Y%m%d).yaml` | After changes | +| Audit log export | `cp ~/.clawdbot/audit*.jsonl evidence/` | Daily | +| Metrics snapshot | `curl localhost:18789/metrics > metrics-$(date +%Y%m%d).txt` | Weekly | + +### Manual Evidence + +| Evidence Type | Collection Method | Frequency | +|--------------|-------------------|-----------| +| Access review records | Document review meetings | Quarterly | +| Incident records | Completed incident templates | Per incident | +| Training records | Training completion certificates | Annually | +| Policy acknowledgments | Signed policy forms | At hire, annually | + +### Evidence Retention + +| Evidence Type | Retention Period | Storage | +|--------------|------------------|---------| +| Audit logs | 1 year | Secure backup | +| Security audits | 2 years | Document management | +| Incident records | 3 years | Secure archive | +| Configuration history | 1 year | Version control | + +## Gap Remediation + +### Priority Matrix + +| Severity | Example | Remediation Timeframe | +|----------|---------|----------------------| +| Critical | No gateway auth, wildcard allowlists | Immediate (24 hours) | +| High | RBAC disabled, weak tokens | 1 week | +| Medium | Missing documentation, review overdue | 30 days | +| Low | Informational findings | 90 days | + +### Common Gaps and Remediation + +| Gap | Finding | Remediation | +|-----|---------|-------------| +| No RBAC | `rbac.enabled: false` | Enable RBAC, assign roles | +| Weak auth | Token < 24 chars | Generate strong token | +| Open DMs | `dmPolicy: "open"` | Use pairing or allowlist | +| No audit | Audit file missing | Verify audit logging config | +| Wildcard access | `allowFrom: ["*"]` | Replace with explicit IDs | + +## Compliance Summary Dashboard + +Run this script to generate a compliance status summary: + +```bash +#!/bin/bash +echo "=== Clawdbot Compliance Status ===" +echo "Date: $(date)" +echo "" + +echo "--- Security Audit Summary ---" +clawdbot security audit --summary 2>/dev/null || echo "Security audit failed" +echo "" + +echo "--- RBAC Status ---" +clawdbot config get rbac.enabled 2>/dev/null || echo "RBAC config unavailable" +echo "" + +echo "--- Gateway Auth ---" +clawdbot config get gateway.auth.mode 2>/dev/null || echo "Auth config unavailable" +echo "" + +echo "--- Audit Log Status ---" +if [ -f ~/.clawdbot/audit.jsonl ]; then + echo "Audit log exists" + echo "Last entry: $(tail -1 ~/.clawdbot/audit.jsonl | jq -r '.ts')" + echo "Total events: $(wc -l < ~/.clawdbot/audit.jsonl)" +else + echo "WARNING: No audit log found" +fi +echo "" + +echo "--- Critical Findings ---" +clawdbot security audit --deep 2>/dev/null | grep -i "critical" || echo "No critical findings" +``` + +## Review Schedule + +| Review Type | Frequency | Participants | Output | +|-------------|-----------|--------------|--------| +| Access review | Quarterly | Security, HR | Updated assignments | +| Policy review | Semi-annually | Security, Legal | Updated policies | +| Security audit | Weekly (automated) | Security | Audit report | +| Full compliance assessment | Annually | Security, Audit | Readiness report | + +## Certification Path + +### SOC2 Type II + +1. **Gap assessment** (this checklist) +2. **Remediation** (address critical/high gaps) +3. **Control operation** (3-12 month observation period) +4. **Auditor engagement** +5. **Evidence collection** (automated + manual) +6. **Audit examination** +7. **Report issuance** + +### ISO 27001 + +1. **Gap assessment** (this checklist) +2. **ISMS documentation** +3. **Control implementation** +4. **Internal audit** +5. **Management review** +6. **Certification audit (Stage 1)** +7. **Certification audit (Stage 2)** +8. **Certification** +9. **Surveillance audits** (annually) + +## Related Documentation + +- [Compliance Overview](/compliance/) - Compliance documentation hub +- [Incident Response](/compliance/incident-response) - Incident procedures +- [Access Control Policy](/compliance/access-control-policy) - Access management +- [Security Metrics](/compliance/security-metrics) - Monitoring KPIs +- [Threat Model](/security/threat-model) - Risk assessment + +--- + +*Checklist owner: Security Team* +*Last updated: 2026-01-27* +*Next review: 2026-04-27* diff --git a/docs/compliance/security-metrics.md b/docs/compliance/security-metrics.md new file mode 100644 index 000000000..f19937ecd --- /dev/null +++ b/docs/compliance/security-metrics.md @@ -0,0 +1,535 @@ +--- +title: Security Metrics and KPIs +summary: Key performance indicators and metrics for security monitoring in Clawdbot deployments. +permalink: /compliance/security-metrics/ +--- + +# Security Metrics and KPIs + +This document defines security metrics, key performance indicators (KPIs), and monitoring guidance for Clawdbot deployments. + +## Purpose + +Security metrics enable: +- Continuous monitoring of security controls +- Early detection of security incidents +- Measurement of security program effectiveness +- Evidence collection for compliance audits +- Data-driven security improvements + +## Metrics Sources + +### Audit Logs + +Location: `~/.clawdbot/audit.jsonl` + +Security-relevant event types: +- `auth.login`, `auth.failure`, `auth.logout` +- `rbac.denied` +- `pairing.request`, `pairing.approve`, `pairing.reject`, `pairing.revoke` +- `exec.request`, `exec.approve`, `exec.reject` +- `config.change` +- `gateway.start`, `gateway.stop` + +### Prometheus Metrics + +Endpoint: `GET /metrics` (requires gateway authentication) + +Metrics are defined in `src/observability/metrics-registry.ts` and updated via diagnostic events. + +## Access Control Metrics + +### Authentication Failure Rate + +**Definition**: Percentage of authentication attempts that fail + +**Formula**: `(auth.failure count / total auth attempts) * 100` + +**Threshold**: +| Level | Value | Action | +|-------|-------|--------| +| Normal | < 5% | Monitor | +| Warning | 5-15% | Investigate | +| Critical | > 15% | Incident response | + +**Audit Log Query**: +```bash +# Count auth failures in last hour +FAILURES=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "auth.failure" and .ts > (now - 3600 | todate))' | wc -l) + +# Count total auth attempts +TOTAL=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type | startswith("auth.") and .ts > (now - 3600 | todate))' | wc -l) + +echo "Auth failure rate: $((FAILURES * 100 / TOTAL))%" +``` + +**Prometheus Alert**: +```yaml +- alert: HighAuthFailureRate + expr: | + (increase(clawdbot_auth_failure_total[1h]) / + (increase(clawdbot_auth_login_total[1h]) + increase(clawdbot_auth_failure_total[1h]))) > 0.15 + for: 5m + labels: + severity: critical + annotations: + summary: "Authentication failure rate exceeds 15%" +``` + +### RBAC Denial Rate + +**Definition**: Rate of permission denials per hour + +**Formula**: Count of `rbac.denied` events per hour + +**Threshold**: +| Level | Value | Action | +|-------|-------|--------| +| Normal | < 10/hour | Monitor | +| Warning | 10-50/hour | Review access patterns | +| Critical | > 50/hour | Investigate potential attack | + +**Audit Log Query**: +```bash +# RBAC denials per hour over last 24 hours +cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "rbac.denied")' | \ + jq -s 'group_by(.ts[:13]) | map({hour: .[0].ts[:13], count: length})' +``` + +**Prometheus Alert**: +```yaml +- alert: HighRbacDenialRate + expr: increase(clawdbot_rbac_denied_total[1h]) > 50 + for: 5m + labels: + severity: warning + annotations: + summary: "Unusual RBAC denial rate: {{ $value }} denials/hour" +``` + +### Unique Failed Actors + +**Definition**: Count of distinct actors with authentication failures + +**Formula**: Count of unique `actor.id` values in `auth.failure` events + +**Threshold**: +| Level | Value | Action | +|-------|-------|--------| +| Normal | < 3/hour | Monitor | +| Warning | 3-10/hour | Investigate sources | +| Critical | > 10/hour | Potential attack | + +**Audit Log Query**: +```bash +# Unique actors with auth failures in last hour +cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "auth.failure" and .ts > (now - 3600 | todate))' | \ + jq -s '[.[].actor.id] | unique | length' +``` + +## Incident Metrics + +### Mean Time to Detect (MTTD) + +**Definition**: Average time from incident occurrence to detection + +**Formula**: `(Detection timestamp - Incident start timestamp) / Number of incidents` + +**Target**: < 15 minutes for P1/P2 incidents + +**Measurement**: +- Track detection time in incident records +- Compare against first suspicious audit event timestamp +- Review alert trigger times + +### Mean Time to Contain (MTTC) + +**Definition**: Average time from detection to containment + +**Formula**: `(Containment timestamp - Detection timestamp) / Number of incidents` + +**Target**: +| Severity | Target MTTC | +|----------|-------------| +| P1 | < 30 minutes | +| P2 | < 2 hours | +| P3 | < 8 hours | +| P4 | < 24 hours | + +### Mean Time to Resolve (MTTR) + +**Definition**: Average time from detection to full resolution + +**Formula**: `(Resolution timestamp - Detection timestamp) / Number of incidents` + +**Target**: +| Severity | Target MTTR | +|----------|-------------| +| P1 | < 4 hours | +| P2 | < 24 hours | +| P3 | < 72 hours | +| P4 | < 1 week | + +### Incident Volume + +**Definition**: Count of security incidents by severity over time + +**Audit Log Query**: +```bash +# Security events that may indicate incidents +cat ~/.clawdbot/audit.jsonl | jq -c 'select(.outcome == "failure" or .outcome == "denied")' | \ + jq -s 'group_by(.type) | map({type: .[0].type, count: length}) | sort_by(.count) | reverse' +``` + +## Operational Metrics + +### Gateway Uptime + +**Definition**: Percentage of time gateway is operational + +**Formula**: `(Uptime seconds / Total period seconds) * 100` + +**Target**: > 99.9% + +**Prometheus Metric**: +```prometheus +clawdbot_gateway_uptime_seconds +``` + +**Alert**: +```yaml +- alert: GatewayDown + expr: up{job="clawdbot"} == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "Clawdbot gateway is down" +``` + +### Rate Limit Activations + +**Definition**: Count of rate limit enforcements + +**Formula**: Count of rate limit events per hour + +**Threshold**: +| Level | Value | Action | +|-------|-------|--------| +| Normal | < 10/hour | Monitor | +| Warning | 10-100/hour | Review traffic patterns | +| Critical | > 100/hour | Potential DoS | + +### Security Audit Score + +**Definition**: Count of findings by severity from automated security audit + +**Formula**: Run `clawdbot security audit --summary` and track over time + +**Target**: +- Critical findings: 0 +- Warning findings: < 5 +- Info findings: Tracked but not alarmed + +**Collection Script**: +```bash +#!/bin/bash +# Collect security audit metrics +DATE=$(date +%Y-%m-%d) +OUTPUT=$(clawdbot security audit --summary 2>/dev/null) + +CRITICAL=$(echo "$OUTPUT" | grep -oP 'critical:\s*\K\d+' || echo 0) +WARNING=$(echo "$OUTPUT" | grep -oP 'warn:\s*\K\d+' || echo 0) +INFO=$(echo "$OUTPUT" | grep -oP 'info:\s*\K\d+' || echo 0) + +echo "$DATE,$CRITICAL,$WARNING,$INFO" >> security-audit-trend.csv +``` + +## Channel Security Metrics + +### Pairing Approval Rate + +**Definition**: Percentage of pairing requests that are approved + +**Formula**: `(pairing.approve count / pairing.request count) * 100` + +**Threshold**: Low approval rate may indicate attack attempts + +**Audit Log Query**: +```bash +# Pairing metrics for last 30 days +REQUESTS=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "pairing.request")' | wc -l) +APPROVED=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "pairing.approve")' | wc -l) +REJECTED=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "pairing.reject")' | wc -l) + +echo "Pairing requests: $REQUESTS" +echo "Approved: $APPROVED ($((APPROVED * 100 / REQUESTS))%)" +echo "Rejected: $REJECTED ($((REJECTED * 100 / REQUESTS))%)" +``` + +### Command Rejection Rate + +**Definition**: Percentage of exec requests that are rejected + +**Formula**: `(exec.reject count / total exec events) * 100` + +**Threshold**: +| Level | Value | Interpretation | +|-------|-------|----------------| +| Normal | < 5% | Policy working as expected | +| Elevated | 5-20% | Review blocked commands | +| High | > 20% | Potential abuse or misconfiguration | + +## Grafana Dashboard + +### Dashboard JSON + +```json +{ + "title": "Clawdbot Security Metrics", + "panels": [ + { + "title": "Authentication Failures", + "type": "stat", + "gridPos": {"h": 4, "w": 6, "x": 0, "y": 0}, + "targets": [ + {"expr": "increase(clawdbot_auth_failure_total[24h])", "legendFormat": "24h failures"} + ], + "fieldConfig": { + "defaults": { + "thresholds": { + "steps": [ + {"value": 0, "color": "green"}, + {"value": 10, "color": "yellow"}, + {"value": 50, "color": "red"} + ] + } + } + } + }, + { + "title": "RBAC Denials Rate", + "type": "graph", + "gridPos": {"h": 8, "w": 12, "x": 0, "y": 4}, + "targets": [ + {"expr": "rate(clawdbot_rbac_denied_total[5m])", "legendFormat": "Denials/sec"} + ] + }, + { + "title": "Gateway Uptime", + "type": "stat", + "gridPos": {"h": 4, "w": 6, "x": 6, "y": 0}, + "targets": [ + {"expr": "clawdbot_gateway_uptime_seconds / 86400", "legendFormat": "Days"} + ], + "fieldConfig": { + "defaults": {"unit": "d"} + } + }, + { + "title": "Message Processing by Outcome", + "type": "piechart", + "gridPos": {"h": 8, "w": 6, "x": 12, "y": 4}, + "targets": [ + {"expr": "sum by (outcome) (clawdbot_message_processed_total)", "legendFormat": "{{outcome}}"} + ] + }, + { + "title": "Security Events Timeline", + "type": "graph", + "gridPos": {"h": 8, "w": 18, "x": 0, "y": 12}, + "targets": [ + {"expr": "rate(clawdbot_auth_failure_total[5m])", "legendFormat": "Auth failures"}, + {"expr": "rate(clawdbot_rbac_denied_total[5m])", "legendFormat": "RBAC denials"} + ] + } + ] +} +``` + +### Prometheus Recording Rules + +Pre-compute common aggregations for dashboard performance: + +```yaml +groups: + - name: clawdbot-security-recording + rules: + - record: clawdbot:auth_failure_rate_1h + expr: increase(clawdbot_auth_failure_total[1h]) + + - record: clawdbot:rbac_denied_rate_1h + expr: increase(clawdbot_rbac_denied_total[1h]) + + - record: clawdbot:message_error_rate_5m + expr: | + rate(clawdbot_message_processed_total{outcome="error"}[5m]) / + rate(clawdbot_message_processed_total[5m]) +``` + +## Alerting Rules + +### Complete Alert Configuration + +```yaml +groups: + - name: clawdbot-security-alerts + rules: + # Authentication alerts + - alert: HighAuthFailureRate + expr: clawdbot:auth_failure_rate_1h > 50 + for: 5m + labels: + severity: warning + annotations: + summary: "High authentication failure rate" + description: "{{ $value }} auth failures in the last hour" + runbook_url: "/compliance/incident-response#authentication" + + - alert: BruteForceAttempt + expr: clawdbot:auth_failure_rate_1h > 100 + for: 2m + labels: + severity: critical + annotations: + summary: "Possible brute force attack" + description: "{{ $value }} auth failures in the last hour" + + # RBAC alerts + - alert: RbacDenialSpike + expr: clawdbot:rbac_denied_rate_1h > 25 + for: 5m + labels: + severity: warning + annotations: + summary: "Unusual RBAC denial rate" + + # Availability alerts + - alert: GatewayDown + expr: up{job="clawdbot"} == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "Gateway is down" + + - alert: HighMessageErrorRate + expr: clawdbot:message_error_rate_5m > 0.1 + for: 5m + labels: + severity: warning + annotations: + summary: "High message processing error rate" + description: "{{ $value | humanizePercentage }} of messages failing" + + # Queue alerts + - alert: QueueBacklog + expr: clawdbot_queue_depth > 100 + for: 5m + labels: + severity: warning + annotations: + summary: "Message queue backlog building" +``` + +## Reporting + +### Weekly Security Report Template + +```markdown +# Weekly Security Report: [Week of YYYY-MM-DD] + +## Executive Summary +- Overall security posture: [Good/Fair/Needs Attention] +- Open incidents: [count] +- New vulnerabilities: [count] + +## Key Metrics + +### Access Control +| Metric | Value | Target | Status | +|--------|-------|--------|--------| +| Auth failure rate | X% | < 5% | [OK/WARN] | +| RBAC denials | X/week | < 70 | [OK/WARN] | +| Unique failed actors | X | < 21 | [OK/WARN] | + +### Incident Response +| Metric | Value | Target | Status | +|--------|-------|--------|--------| +| MTTD (average) | X min | < 15 min | [OK/WARN] | +| MTTC (average) | X hours | < 2 hours | [OK/WARN] | +| Incidents this week | X | - | [Info] | + +### Availability +| Metric | Value | Target | Status | +|--------|-------|--------|--------| +| Gateway uptime | X% | > 99.9% | [OK/WARN] | +| Security audit score | X critical | 0 | [OK/WARN] | + +## Incidents +[Summary of any incidents] + +## Audit Findings +[New findings from security audit] + +## Action Items +- [ ] [Action item 1] +- [ ] [Action item 2] + +## Next Week Focus +[Planned security activities] +``` + +### Automated Report Generation + +```bash +#!/bin/bash +# Generate weekly security metrics report + +WEEK=$(date +%Y-W%V) +OUTPUT="security-report-$WEEK.md" + +echo "# Weekly Security Report: $WEEK" > $OUTPUT +echo "" >> $OUTPUT + +echo "## Access Control Metrics" >> $OUTPUT +echo "" >> $OUTPUT + +# Auth failures +FAILURES=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "auth.failure" and .ts > (now - 604800 | todate))' | wc -l) +echo "- Authentication failures: $FAILURES" >> $OUTPUT + +# RBAC denials +DENIALS=$(cat ~/.clawdbot/audit.jsonl | jq -c 'select(.type == "rbac.denied" and .ts > (now - 604800 | todate))' | wc -l) +echo "- RBAC denials: $DENIALS" >> $OUTPUT + +echo "" >> $OUTPUT +echo "## Security Audit Summary" >> $OUTPUT +clawdbot security audit --summary 2>/dev/null >> $OUTPUT + +echo "" >> $OUTPUT +echo "Report generated: $(date)" >> $OUTPUT +``` + +## Compliance Evidence + +Use these metrics as evidence for compliance audits: + +| SOC2 Criteria | Metric | Evidence Collection | +|---------------|--------|---------------------| +| CC4.1 | Gateway uptime, audit log completeness | Export uptime metrics, verify audit rotation | +| CC6.2 | Auth failure rate, RBAC denials | Export access control metrics | +| CC7.3 | MTTD, MTTC, MTTR | Document incident timelines | + +## Related Documentation + +- [Observability Guide](/enterprise/observability) - Prometheus and Grafana setup +- [Incident Response](/compliance/incident-response) - Incident handling procedures +- [Readiness Checklist](/compliance/readiness-checklist) - Compliance verification +- [Security Hardening](/enterprise/security-hardening) - Security configuration + +--- + +*Document owner: Security Team* +*Last reviewed: 2026-01-27* +*Next review: 2026-07-27* diff --git a/docs/compliance/vulnerability-disclosure.md b/docs/compliance/vulnerability-disclosure.md new file mode 100644 index 000000000..1da9d5fc5 --- /dev/null +++ b/docs/compliance/vulnerability-disclosure.md @@ -0,0 +1,230 @@ +--- +title: Vulnerability Disclosure Policy +summary: Responsible disclosure policy for reporting security vulnerabilities in Clawdbot. +permalink: /compliance/vulnerability-disclosure/ +--- + +# Vulnerability Disclosure Policy + +This policy describes how to report security vulnerabilities in Clawdbot and how we handle disclosures. + +## Reporting a Vulnerability + +### Preferred Channels + +**GitHub Security Advisories (Recommended)** + +Report vulnerabilities privately through GitHub Security Advisories: + +1. Go to [Clawdbot Security Advisories](https://github.com/clawdbot/clawdbot/security/advisories) +2. Click "Report a vulnerability" +3. Provide details following the template below + +**Email** + +For reporters who cannot use GitHub: +- Email: security@clawd.bot +- Encrypt sensitive details using our PGP key (available at the repository) + +### What to Include + +Your report should include: + +| Field | Description | +|-------|-------------| +| **Summary** | Brief description of the vulnerability | +| **Severity** | Your assessment: Critical, High, Medium, Low | +| **Affected versions** | Which Clawdbot versions are affected | +| **Attack vector** | How the vulnerability can be exploited | +| **Impact** | What an attacker could achieve | +| **Reproduction steps** | Step-by-step instructions to reproduce | +| **Proof of concept** | Code, screenshots, or logs demonstrating the issue | +| **Suggested fix** | If you have recommendations | + +### Example Report + +``` +## Summary +Authentication bypass in gateway pairing mechanism + +## Severity +High + +## Affected Versions +Clawdbot 2024.1.0 through 2024.1.15 + +## Attack Vector +Remote, requires network access to gateway + +## Impact +Attacker could pair a device without valid pairing code under specific timing conditions + +## Reproduction Steps +1. Start Clawdbot gateway with default configuration +2. Initiate pairing request from attacker device +3. Send rapid concurrent pairing attempts with invalid codes +4. Under race condition, one attempt may succeed + +## Proof of Concept +[Attached script or detailed steps] + +## Suggested Fix +Add mutex lock around pairing code validation +``` + +## Response Timeline + +| Phase | Timeline | Description | +|-------|----------|-------------| +| Acknowledgment | 2 business days | Confirm receipt of report | +| Initial assessment | 5 business days | Determine validity and severity | +| Status update | 10 business days | Provide fix timeline or request more info | +| Fix development | Varies by severity | Develop and test remediation | +| Coordinated disclosure | 90 days max | Public disclosure after fix available | + +### Severity-Based Response + +| Severity | Target Fix Time | Disclosure Timeline | +|----------|-----------------|---------------------| +| Critical | 7 days | 14 days after fix | +| High | 30 days | 30 days after fix | +| Medium | 60 days | 60 days after fix | +| Low | 90 days | 90 days after fix | + +## Safe Harbor + +We want security researchers to feel comfortable reporting vulnerabilities. If you: + +- Act in good faith to avoid privacy violations, data destruction, and service disruption +- Only interact with accounts you own or have explicit permission to test +- Do not exploit vulnerabilities beyond what is necessary to demonstrate the issue +- Report vulnerabilities promptly and do not disclose publicly before coordinated disclosure +- Do not demand payment for vulnerability information + +Then we commit to: + +- Not pursuing legal action against you for security research conducted in accordance with this policy +- Working with you to understand and resolve the issue quickly +- Recognizing your contribution (with your permission) in our security acknowledgments +- Keeping you informed of our progress toward remediation + +## Scope + +### In Scope + +| Component | Description | +|-----------|-------------| +| Clawdbot CLI | Core command-line application | +| Gateway | WebSocket server and HTTP endpoints | +| Channel integrations | WhatsApp, Telegram, Discord, Slack, Signal, iMessage | +| Plugins | Official Clawdbot plugins | +| Configuration | Security of config files and credentials | +| Authentication | Gateway auth, pairing, RBAC | + +### Out of Scope + +| Component | Reason | +|-----------|--------| +| Third-party services | Report to respective providers (OpenAI, Anthropic, etc.) | +| Messaging platform bugs | Report to WhatsApp, Telegram, Discord, etc. | +| User configuration errors | Covered by security audit and hardening guide | +| Social engineering | Not a software vulnerability | +| Physical attacks | Out of scope for software security | +| Denial of service | Unless it reveals an amplification vector | + +### Qualifying Vulnerabilities + +| Category | Examples | +|----------|----------| +| Authentication bypass | Accessing gateway without valid credentials | +| Authorization bypass | Accessing resources beyond granted permissions | +| Injection attacks | Command injection, prompt injection with security impact | +| Information disclosure | Credential leakage, sensitive data exposure | +| Cryptographic issues | Weak encryption, improper key handling | +| Logic flaws | Security control bypass, race conditions | + +### Non-Qualifying Issues + +| Category | Examples | +|----------|----------| +| Best practices | Missing headers without demonstrated impact | +| Self-XSS | Requires victim to inject malicious content | +| Rate limiting bypass | Without security impact | +| Version disclosure | Unless it reveals specific vulnerable version | +| Already reported | Duplicate of known issue | + +## Coordinated Disclosure + +We follow coordinated disclosure principles: + +1. **Reporter contacts us** with vulnerability details +2. **We acknowledge** receipt within 2 business days +3. **We assess** severity and develop fix +4. **We coordinate** disclosure date with reporter +5. **We release** fix and publish advisory +6. **Reporter may publish** after coordinated disclosure date + +### Disclosure Content + +Our security advisories include: +- Vulnerability description +- Affected versions +- Fixed versions +- Severity rating (CVSS if applicable) +- Mitigation steps +- Credit to reporter (if desired) + +### Early Disclosure Exceptions + +We may disclose earlier if: +- Vulnerability is being actively exploited +- Public disclosure is imminent from another source +- Significant user harm can be prevented + +We may request delayed disclosure if: +- Fix requires significant development time +- Coordinating with dependent projects +- Critical infrastructure implications + +## Recognition + +We maintain a Security Hall of Fame for researchers who report valid vulnerabilities: + +- Acknowledgment in security advisory +- Listed in SECURITY.md (with permission) +- Letter of appreciation (on request) + +We do not currently offer monetary bounties, but we deeply appreciate responsible disclosure. + +## Legal + +This policy is not a license to conduct security research on systems you do not own or have permission to test. + +Always obtain proper authorization before testing. This policy applies only to: +- Your own Clawdbot installations +- Test environments you control +- Systems where you have explicit written permission + +Unauthorized access to computer systems is illegal. This policy does not authorize any activity that would violate applicable laws. + +## Contact + +- **Security reports**: [GitHub Security Advisories](https://github.com/clawdbot/clawdbot/security/advisories) (preferred) +- **Email**: security@clawd.bot +- **General questions**: Use GitHub Issues (do not disclose vulnerabilities publicly) + +## Policy Updates + +This policy may be updated periodically. Significant changes will be announced in the repository. + +## Related Documentation + +- [Threat Model](/security/threat-model) - Security architecture and known risks +- [Incident Response](/compliance/incident-response) - How we handle security incidents +- [Security Hardening](/enterprise/security-hardening) - Secure configuration guide + +--- + +*Policy owner: Security Team* +*Effective date: 2026-01-27* +*Last reviewed: 2026-01-27* diff --git a/docs/docs.json b/docs/docs.json index a463479aa..3e26cc720 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1111,6 +1111,27 @@ "platforms/mac/peekaboo" ] }, + { + "group": "Enterprise & Compliance", + "pages": [ + "enterprise/security-hardening", + "enterprise/observability", + "compliance/index", + "compliance/incident-response", + "compliance/access-control-policy", + "compliance/change-management", + "compliance/vulnerability-disclosure", + "compliance/security-metrics", + "compliance/readiness-checklist" + ] + }, + { + "group": "Security", + "pages": [ + "security/threat-model", + "security/data-handling" + ] + }, { "group": "Reference & Templates", "pages": [