@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/compliance-patterns/soc2/audit-logging.md

@@ -0,0 +1,458 @@
+# SOC2 Audit Logging for Zoho
+
+## Why Custom Logging is Required
+
+Zoho Creator does NOT automatically log:
+- Deluge script executions
+- API calls made via `invokeUrl`
+- Record reads (only modifications are logged natively)
+- Export/download events
+- Failed access attempts
+
+For SOC2 Trust Service Criteria (specifically CC7.2 and CC7.3), you MUST implement custom audit logging for all sensitive operations.
+
+---
+
+## SOC2 Trust Service Criteria Mapping
+
+| Criteria | Requirement | Implementation |
+|----------|-------------|----------------|
+| CC6.1 | Logical access controls | Role-based field permissions |
+| CC6.2 | User authentication | Zoho login + MFA |
+| CC6.3 | Access management | Quarterly access reviews |
+| CC7.1 | Change management | Change_Request form + approval workflow |
+| CC7.2 | System monitoring | Custom audit logging (this document) |
+| CC7.3 | Anomaly detection | Scheduled queries on audit data |
+| CC8.1 | Incident response | Incident form + escalation workflow |
+
+---
+
+## Audit Log Form Structure
+
+```
+Form: SOC2_Audit_Log
+Fields:
+  - Log_ID (Auto-number, primary key)
+  - Timestamp (DateTime, auto-filled: zoho.currenttime)
+  - User_ID (Single Line, auto-filled: zoho.loginuserid)
+  - User_Email (Email, auto-filled: zoho.loginuser)
+  - User_Role (Single Line, auto-filled: zoho.loginuserRole)
+  - Action_Type (Picklist: CREATE/READ/UPDATE/DELETE/EXPORT/LOGIN/LOGOUT/DENIED/ADMIN)
+  - Target_Form (Single Line)
+  - Target_Record_ID (Single Line)
+  - Field_Name (Single Line, nullable - for field-level changes)
+  - Old_Value (Multi Line, nullable - before state)
+  - New_Value (Multi Line, nullable - after state)
+  - IP_Address (Single Line, auto-filled: zoho.ipaddress)
+  - Result (Picklist: SUCCESS/FAILURE/DENIED)
+  - Risk_Level (Picklist: LOW/MEDIUM/HIGH/CRITICAL)
+  - Session_ID (Single Line, nullable)
+  - Notes (Multi Line, nullable)
+
+Permissions:
+  - Create: All roles (via Deluge only, not direct form access)
+  - Edit: None (logs are immutable)
+  - Delete: None (logs are immutable)
+  - View: Admin, Compliance, Auditor roles only
+```
+
+---
+
+## Core Logging Function
+
+```deluge
+// ============================================================
+// FUNCTION: logAuditEvent
+// PURPOSE: Create an immutable audit log entry for SOC2 compliance
+// USAGE: Call in EVERY workflow that reads, modifies, or deletes data
+// ============================================================
+
+void logAuditEvent(String actionType, String targetForm, String recordId, Map changes, String riskLevel)
+{
+    logMap = Map();
+    logMap.put("Timestamp", zoho.currenttime);
+    logMap.put("User_ID", zoho.loginuserid);
+    logMap.put("User_Email", zoho.loginuser);
+    logMap.put("User_Role", ifnull(zoho.loginuserRole, "system"));
+    logMap.put("Action_Type", actionType);
+    logMap.put("Target_Form", targetForm);
+    logMap.put("Target_Record_ID", recordId);
+    logMap.put("IP_Address", ifnull(zoho.ipaddress, "internal"));
+    logMap.put("Result", "SUCCESS");
+    logMap.put("Risk_Level", riskLevel);
+
+    // Store field-level changes
+    if (changes != null && changes.size() > 0)
+    {
+        if (changes.containsKey("field"))
+        {
+            logMap.put("Field_Name", changes.get("field"));
+        }
+        if (changes.containsKey("old"))
+        {
+            logMap.put("Old_Value", changes.get("old"));
+        }
+        if (changes.containsKey("new"))
+        {
+            logMap.put("New_Value", changes.get("new"));
+        }
+    }
+
+    zoho.creator.createRecord("app", "SOC2_Audit_Log", logMap);
+}
+```
+
+### Usage in Workflows
+
+```deluge
+// On Record Create
+logAuditEvent("CREATE", "Customers", input.ID.toString(), null, "LOW");
+
+// On Record Update (with before/after)
+changes = Map();
+changes.put("field", "Status");
+changes.put("old", input.previous.Status);
+changes.put("new", input.Status);
+logAuditEvent("UPDATE", "Customers", input.ID.toString(), changes, "MEDIUM");
+
+// On Record Delete
+logAuditEvent("DELETE", "Invoices", input.ID.toString(), null, "HIGH");
+
+// On Failed Access Attempt
+failMap = Map();
+failMap.put("Timestamp", zoho.currenttime);
+failMap.put("User_Email", zoho.loginuser);
+failMap.put("Action_Type", "DENIED");
+failMap.put("Target_Form", "Financial_Records");
+failMap.put("Result", "DENIED");
+failMap.put("Risk_Level", "CRITICAL");
+failMap.put("Notes", "Insufficient role for financial data access");
+zoho.creator.createRecord("app", "SOC2_Audit_Log", failMap);
+```
+
+---
+
+## BigQuery Export for Long-Term Retention
+
+SOC2 requires audit logs to be retained for the engagement period (typically 12 months minimum, often longer per client contract). Export to BigQuery for cost-effective long-term storage.
+
+### BigQuery Audit Table
+
+```sql
+CREATE TABLE `project.compliance.soc2_audit_logs` (
+  log_id STRING NOT NULL,
+  timestamp TIMESTAMP NOT NULL,
+  user_id STRING,
+  user_email STRING NOT NULL,
+  user_role STRING,
+  action_type STRING NOT NULL,
+  target_form STRING NOT NULL,
+  target_record_id STRING,
+  field_name STRING,
+  old_value STRING,
+  new_value STRING,
+  ip_address STRING,
+  result STRING NOT NULL,
+  risk_level STRING,
+  session_id STRING,
+  notes STRING,
+  client_id STRING NOT NULL,
+  source_org STRING NOT NULL,
+  archive_date TIMESTAMP NOT NULL,
+  archive_batch_id STRING NOT NULL
+)
+PARTITION BY DATE(timestamp)
+CLUSTER BY client_id, action_type, user_email;
+```
+
+### Automated Monthly Export (Catalyst Cron)
+
+```javascript
+'use strict';
+
+const catalyst = require('zcatalyst-sdk-node');
+const { BigQuery } = require('@google-cloud/bigquery');
+
+module.exports = async (cronDetails, context) => {
+  const app = catalyst.initialize(context);
+  const bigquery = new BigQuery();
+  const batchId = `soc2-${Date.now()}`;
+  let exportedCount = 0;
+
+  try {
+    // Calculate date range: previous month
+    const now = new Date();
+    const startDate = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+    const endDate = new Date(now.getFullYear(), now.getMonth(), 0);
+
+    console.log(`Exporting SOC2 logs: ${startDate.toISOString()} to ${endDate.toISOString()}`);
+
+    // Fetch logs from Creator (paginated)
+    const allLogs = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const criteria = `Timestamp >= "${startDate.toISOString()}" && Timestamp <= "${endDate.toISOString()}"`;
+      const response = await fetchCreatorRecords(app, 'SOC2_Audit_Log', criteria, page);
+
+      if (response.length > 0) {
+        allLogs.push(...response);
+        page++;
+      } else {
+        hasMore = false;
+      }
+
+      if (page > 100) {
+        console.log('Safety limit reached at page 100');
+        hasMore = false;
+      }
+    }
+
+    if (allLogs.length === 0) {
+      console.log('No logs to export for this period');
+      context.close();
+      return;
+    }
+
+    // Transform for BigQuery
+    const rows = allLogs.map(log => ({
+      log_id: String(log.Log_ID),
+      timestamp: log.Timestamp,
+      user_id: log.User_ID,
+      user_email: log.User_Email,
+      user_role: log.User_Role,
+      action_type: log.Action_Type,
+      target_form: log.Target_Form,
+      target_record_id: log.Target_Record_ID,
+      field_name: log.Field_Name || null,
+      old_value: log.Old_Value || null,
+      new_value: log.New_Value || null,
+      ip_address: log.IP_Address,
+      result: log.Result,
+      risk_level: log.Risk_Level || 'LOW',
+      session_id: log.Session_ID || null,
+      notes: log.Notes || null,
+      client_id: process.env.CLIENT_ID,
+      source_org: process.env.ZOHO_ORG_ID,
+      archive_date: new Date().toISOString(),
+      archive_batch_id: batchId
+    }));
+
+    // Insert into BigQuery
+    const dataset = bigquery.dataset('compliance');
+    const table = dataset.table('soc2_audit_logs');
+    await table.insert(rows);
+    exportedCount = rows.length;
+
+    console.log(`Exported ${exportedCount} SOC2 audit logs (batch: ${batchId})`);
+  } catch (error) {
+    console.error(`SOC2 export error: ${error.message}`);
+    // Send alert to compliance team
+  } finally {
+    context.close(); // MANDATORY
+  }
+};
+
+async function fetchCreatorRecords(app, formName, criteria, page) {
+  // Use Zoho Creator API to fetch records
+  // Implementation depends on your OAuth setup
+  return [];
+}
+```
+
+---
+
+## Log Rotation and Retention
+
+| Environment | Retention Period | Storage | Cost |
+|-------------|-----------------|---------|------|
+| Creator (live) | 3 months | Zoho storage | Included in plan |
+| BigQuery (archive) | 3 years minimum | GCS long-term | ~$0.01/GB/month |
+| Cold storage (legal hold) | 7 years | GCS Archive class | ~$0.004/GB/month |
+
+### Rotation Schedule
+
+- **Monthly**: Export previous month's logs to BigQuery
+- **Quarterly**: Verify export completeness (Creator count vs. BigQuery count)
+- **Annually**: Move logs older than 3 years to cold storage
+- **On demand**: Export on auditor request
+
+---
+
+## Anomaly Detection Queries
+
+### Unusual Access Patterns
+
+```sql
+-- Users accessing significantly more records than their average
+WITH user_daily AS (
+  SELECT user_email, DATE(timestamp) AS access_date,
+         COUNT(*) AS daily_actions
+  FROM `project.compliance.soc2_audit_logs`
+  WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 90 DAY)
+  GROUP BY user_email, DATE(timestamp)
+),
+user_stats AS (
+  SELECT user_email,
+         AVG(daily_actions) AS avg_daily,
+         STDDEV(daily_actions) AS stddev_daily
+  FROM user_daily
+  GROUP BY user_email
+)
+SELECT d.user_email, d.access_date, d.daily_actions,
+       s.avg_daily, s.stddev_daily
+FROM user_daily d
+JOIN user_stats s ON d.user_email = s.user_email
+WHERE d.daily_actions > s.avg_daily + (3 * s.stddev_daily)
+ORDER BY d.daily_actions DESC;
+```
+
+### After-Hours Access
+
+```sql
+-- Access outside business hours (adjust timezone as needed)
+SELECT user_email, timestamp, action_type, target_form, target_record_id
+FROM `project.compliance.soc2_audit_logs`
+WHERE (EXTRACT(HOUR FROM timestamp) < 7 OR EXTRACT(HOUR FROM timestamp) > 19)
+  AND EXTRACT(DAYOFWEEK FROM timestamp) NOT IN (1, 7)  -- Not weekends
+  AND action_type IN ('READ', 'UPDATE', 'DELETE', 'EXPORT')
+  AND timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
+ORDER BY timestamp DESC;
+```
+
+### Failed Access Attempts
+
+```sql
+-- Multiple denied attempts (potential unauthorized access)
+SELECT user_email, DATE(timestamp) AS attempt_date,
+       COUNT(*) AS denied_count,
+       ARRAY_AGG(DISTINCT target_form) AS attempted_forms
+FROM `project.compliance.soc2_audit_logs`
+WHERE result = 'DENIED'
+  AND timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
+GROUP BY user_email, DATE(timestamp)
+HAVING denied_count >= 3
+ORDER BY denied_count DESC;
+```
+
+---
+
+## Change Management Workflow
+
+Since Creator lacks native change management, implement a custom approval flow:
+
+### Change Request Form
+
+```
+Form: Change_Request
+Fields:
+  - Request_ID (Auto-number)
+  - Requested_By (Email, auto-filled)
+  - Request_Date (DateTime, auto-filled)
+  - Change_Type (Picklist: Schema/Workflow/Permission/Integration/Config)
+  - Description (Multi Line, required)
+  - Justification (Multi Line, required)
+  - Risk_Assessment (Picklist: Low/Medium/High/Critical)
+  - Affected_Forms (Multi Select)
+  - Rollback_Plan (Multi Line, required)
+  - Approval_Status (Picklist: Pending/Approved/Rejected/Implemented/Rolled Back)
+  - Approved_By (Email, nullable)
+  - Approval_Date (DateTime, nullable)
+  - Implementation_Date (DateTime, nullable)
+  - Implementation_Notes (Multi Line, nullable)
+  - Verification_Status (Picklist: Pending/Passed/Failed)
+```
+
+### Approval Workflow (Blueprint)
+
+```
+States: Draft → Pending Review → Approved → Implementing → Verified → Closed
+                              ↘ Rejected
+                                          ↘ Rollback Required → Rolled Back → Closed
+
+Transitions:
+  Draft → Pending Review: Submitter fills all required fields
+  Pending Review → Approved: Manager approves (requires different user)
+  Pending Review → Rejected: Manager provides rejection reason
+  Approved → Implementing: Developer begins implementation
+  Implementing → Verified: QA confirms change works correctly
+  Implementing → Rollback Required: Issue detected
+  Verified → Closed: Auto-log completion in audit trail
+```
+
+---
+
+## Quarterly Access Review Process
+
+### Review Checklist
+
+- [ ] Export all active user permissions from Creator
+- [ ] Compare against approved access matrix
+- [ ] Identify users with access no longer justified
+- [ ] Revoke unnecessary permissions
+- [ ] Document all changes in Change_Request form
+- [ ] Get manager sign-off on access decisions
+- [ ] Update access matrix document
+- [ ] Log review completion in SOC2_Audit_Log
+
+### Access Review Query
+
+```sql
+-- All users and their most recent activity
+SELECT user_email, user_role,
+       MAX(timestamp) AS last_activity,
+       COUNT(*) AS total_actions_90d,
+       ARRAY_AGG(DISTINCT action_type) AS action_types,
+       ARRAY_AGG(DISTINCT target_form) AS accessed_forms
+FROM `project.compliance.soc2_audit_logs`
+WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 90 DAY)
+GROUP BY user_email, user_role
+ORDER BY last_activity DESC;
+```
+
+---
+
+## Alerting Configuration
+
+| Condition | Alert Level | Notify | Response Time |
+|-----------|-------------|--------|---------------|
+| 5+ DENIED events in 1 hour | Critical | Admin + Compliance | Immediate |
+| DELETE on financial form | High | Admin | Within 1 hour |
+| EXPORT of >1000 records | High | Data Owner | Within 4 hours |
+| After-hours ADMIN action | Medium | Admin | Next business day |
+| New user first login | Low | Admin | Acknowledge within 24h |
+
+### Alert Implementation (Scheduled Function)
+
+```deluge
+// Scheduled function: runs every 15 minutes
+// Check for critical alert conditions
+
+oneHourAgo = zoho.currenttime.subHour(1);
+criteria = "Result == \"DENIED\" && Timestamp >= \"" + oneHourAgo + "\"";
+deniedLogs = zoho.creator.getRecords("app", "SOC2_Audit_Log_Report", criteria, 1, 200);
+
+// Group by user
+userDenials = Map();
+for each log in deniedLogs
+{
+    email = log.get("User_Email");
+    count = ifnull(userDenials.get(email), 0) + 1;
+    userDenials.put(email, count);
+}
+
+// Alert if any user has 5+ denials
+for each entry in userDenials.entries()
+{
+    if (entry.getValue() >= 5)
+    {
+        sendmail [
+            from: zoho.adminuserid
+            to: "compliance@cloudstreamsoftware.com"
+            subject: "[CRITICAL] SOC2 Alert: Multiple access denials - " + entry.getKey()
+            message: entry.getKey() + " has " + entry.getValue() + " denied access attempts in the last hour. Investigate immediately."
+        ];
+    }
+}
+```