Evidenceops

Prerequisites

Before using this skill, ensure:

1. Plugin @openclaw/evidence-vault is installed and initialized
2. Vault storage directory is configured with appropriate permissions
3. Channel allowlist is configured for trusted sources only
4. Retention policies comply with your legal requirements

Workflow

Step 1: Receive Media

When media is received via any channel:

User sends: [image/video/document]

Required Information:

• File content (from attachment)
• Original filename
• Source channel (whatsapp, telegram, email, etc.)
• Sender identifier
• Message ID (if available)

Step 2: Create or Select Case

IF user specifies existing caseId:
  USE that caseId
ELSE IF user requests new case:
  CREATE case with format: case-{YYYY}-{NNN}
  EXAMPLE: case-2026-001
ELSE:
  ASK user: "Should I create a new case or add to existing case [case-2026-XXX]?"

Case ID Format: case-{year}-{sequence}

• Must match pattern: ^case-[a-zA-Z0-9_-]+$
• Examples: case-2026-001, case-incident-alpha, case-legal-2026-q1

Step 3: Stage Original (Read-Only)

Before ingest:

1. Save received file to temporary staging area
2. Calculate SHA-256 hash immediately
3. Record file size and MIME type
4. DO NOT modify the file

# Staging directory structure
/tmp/evidence-staging/
├── {caseId}/
│   └── {timestamp}-{filename}

Step 4: Extract Metadata

Extract metadata WITHOUT modifying original:

For Images:

• EXIF data (camera, GPS, timestamps)
• Dimensions
• Color profile

For Videos:

• Duration
• Codec information
• Resolution

For Audio:

• Duration
• Sample rate
• Codec

For PDFs:

• Page count
• Author (if embedded)
• Creation date

# Use Read tool or appropriate extraction commands
# NEVER write back to original file

Step 5: Generate Derivatives (Optional)

Create derivative artifacts in SEPARATE folder:

derivatives/
├── thumbnails/
│   └── {evidenceId}-thumb.jpg
├── transcripts/
│   └── {evidenceId}-transcript.txt
└── previews/
    └── {evidenceId}-preview.pdf

Derivative Types:

• thumbnail - Reduced resolution image/video preview
• transcript - Speech-to-text for audio/video
• preview - PDF or text representation
• ocr - Extracted text from images

Step 6: Ingest to Vault

Call the evidence.ingest tool:

{
  "filePath": "/path/to/staged/file",
  "filename": "original-filename.jpg",
  "caseId": "case-2026-001",
  "channel": "whatsapp",
  "sender": "[email protected]",
  "messageId": "msg-abc123",
  "retentionDays": 2555,
  "metadata": {
    "exif": { ... },
    "extracted": { ... }
  }
}

Response:

{
  "success": true,
  "evidenceId": "ev-abc123...",
  "sha256": "a1b2c3...",
  "vaultUrl": "file:///vault/cases/case-2026-001/originals/ev-abc123.jpg",
  "timestamp": "2026-02-17T10:30:00.000Z"
}

Step 7: Update Manifest

The manifest is automatically updated by the ingest operation.

Manifest Location: {vault}/cases/{caseId}/manifest.json

Manifest Contents:

• Case metadata
• Evidence items with hashes
• Derivatives
• Chain of custody entries
• Retention policy

Step 8: Return Receipt

Provide user with evidence receipt:

📋 EVIDENCE RECEIPT

Case ID: case-2026-001
Evidence ID: ev-abc123...
File: original-filename.jpg
SHA-256: a1b2c3d4e5f6...
Size: 1.2 MB
Received: 2026-02-17 10:30:00 UTC
Vault: file:///vault/cases/case-2026-001/originals/ev-abc123.jpg

✅ Chain of custody established
✅ Original preserved immutably
✅ Audit trail active

Tool Reference

evidence.ingest

Ingest a file into the evidence vault.

Parameters:

Returns: { evidenceId, sha256, vaultUrl, timestamp }

evidence.verify

Verify evidence integrity.

Parameters:

Returns: { verified, details: { originalIntact, hashMatch, lastVerifiedAt } }

evidence.manifest

Get case manifest.

Parameters:

Returns: Complete case manifest with all items

evidence.export

Export case as archive.

Parameters:

Returns: { exportPath, sha256, size, itemCount }

evidence.access_log

Get audit trail.

Parameters:

Returns: { events: [ ... ], count }

SECURITY POSTURE

Channel Allowlist Configuration

Configure which channels can submit evidence:

# ~/.openclaw/openclaw.json
{
  "plugins": {
    "evidence-vault": {
      "channelAllowlist": ["whatsapp", "telegram", "email"],
      "channelDenylist": ["public-discord"],
      "requirePairing": true
    }
  }
}

Pairing Requirements

For Direct Messages (DMs):

• REQUIRE pairing before accepting evidence
• BLOCK unpaired DMs by default
• LOG rejected ingestion attempts

For Group Channels:

• VERIFY channel is in allowlist
• REJECT evidence from untrusted channels
• NEVER auto-ingest from public channels

Path Sanitization Rules

ALL paths are validated:

1. No path traversal - ../ sequences rejected
2. No null bytes - \0 rejected
3. No home directory - ~/ rejected
4. Canonicalization - Paths resolved before validation
5. Base path check - Must be within vault directory

Violations result in: E_PATH_TRAVERSAL error + audit log entry

Destructive Action Confirmation

Before any potentially destructive operation:

1. EXPORT - Confirm export destination
2. RETENTION DELETE - Require explicit confirmation (if enabled)
3. LEGAL HOLD RELEASE - Require explicit confirmation

Confirmation format:

⚠️ DESTRUCTIVE ACTION

You are about to: [describe action]
Case: [caseId]
Items affected: [count]

Type "CONFIRM" to proceed:

Secrets Handling

NEVER include in logs or manifests:

• API keys
• Passwords
• Tokens
• Credit card numbers
• Email addresses (redacted)
• Phone numbers (redacted)
• SSN (redacted)

Redaction is automatic via regex patterns.

Troubleshooting

Error: E_PATH_TRAVERSAL

Cause: Filename or path contains disallowed characters

Solution:

• Filenames are automatically sanitized
• If error persists, check for unusual characters
• Original filename is preserved in manifest metadata

Error: E_INVALID_MIME

Cause: File type not in allowed list

Solution:

• Check allowedMimeTypes configuration
• Add MIME type to allowlist if appropriate
• Verify file is not corrupted

Error: E_SIZE_LIMIT

Cause: File exceeds maximum size

Solution:

• Check maxFileSizeBytes configuration
• Split large files if appropriate
• Compress before ingest (note in metadata)

Error: E_CHANNEL_BLOCKED

Cause: Evidence from blocked or non-allowlisted channel

Solution:

• Verify channel in allowlist
• Check if pairing is required
• Review security configuration

Error: E_HASH_MISMATCH

Cause: Evidence file modified after ingest

Solution:

• This indicates potential tampering
• Review access logs for case
• Escalate per incident response procedures

Verification Fails

Symptoms: verified: false in verify response

Diagnostic steps:

1. Check if original file exists
2. Compare current hash with manifest hash
3. Review audit log for modifications
4. Check filesystem permissions

Configuration Example

# openclaw.yaml