Safety System

Overview

The 4-tier safety system protects against accidental destructive operations through risk-based classification, confirmation workflows, dry-run previews, and comprehensive audit logging.

Introduced in v3.0 specifically for the 22 administrative tools, this system prevents costly mistakes while maintaining efficiency for safe operations.

Risk Classification

Every administrative operation is classified into one of four risk levels:

LOW (Risk Level 1)

Read-only operations with zero modification risk.

Behavior: Execute immediately without confirmation.

Examples:

• github_get_repo_settings — View repository configuration
• github_list_collaborators — List repository collaborators
• github_list_webhooks — View webhooks
• github_get_branch_protection — View protection rules

Count: 8 tools

MEDIUM (Risk Level 2)

Reversible changes that can be undone through GitHub’s interface or API.

Behavior:

• strict mode: Requires dry-run confirmation
• moderate mode: Execute directly
• permissive mode: Execute directly

Examples:

• github_create_webhook — Create new webhook (can be deleted)
• github_add_collaborator — Invite user (can be removed)
• github_update_repo_settings — Change settings (can be changed back)

Count: 7 tools

HIGH (Risk Level 3)

Impacts collaboration — affects team access, security rules, or infrastructure.

Behavior:

• strict mode: Requires confirmation token
• moderate mode: Requires confirmation token (default)
• permissive mode: Execute directly

Examples:

• github_remove_collaborator — Revoke user access
• github_delete_webhook — Remove webhook endpoint
• github_update_branch_protection — Modify security rules

Count: 4 tools

CRITICAL (Risk Level 4)

Irreversible operations with permanent consequences.

Behavior: Always requires confirmation token regardless of safety mode.

Examples:

• github_delete_repository — Permanently delete repository
• github_archive_repository — Archive repository (read-only)
• github_delete_branch_protection — Remove all protection rules

Count: 3 tools

CRITICAL operations

These tools are always protected with confirmation tokens, even in disabled safety mode. The system also recommends creating manual backups before execution.

Safety Modes

Choose the appropriate mode for your environment:

Strict Mode

Use case: Production environments, shared repositories, critical infrastructure.

Behavior:

• Confirms MEDIUM+ operations (risk level ≥ 2)
• Enables dry-run by default for destructive changes
• Maximum protection

Configuration:

{
  "mode": "strict",
  "require_confirmation_above": 1
}

Moderate Mode (Default)

Use case: General development, personal projects with occasional collaboration.

Behavior:

• Confirms HIGH+ operations (risk level ≥ 3)
• Balances safety and efficiency
• Recommended for most users

Configuration:

{
  "mode": "moderate",
  "require_confirmation_above": 3
}

Permissive Mode

Use case: Local development, personal repositories, trusted environment.

Behavior:

• Only confirms CRITICAL operations (risk level = 4)
• Minimal friction
• Assumes user expertise

Configuration:

{
  "mode": "permissive",
  "require_confirmation_above": 4
}

Disabled Mode

Use case: Not recommended — automation scripts with full oversight elsewhere.

Behavior:

• No confirmations except CRITICAL operations
• Maximum risk

Configuration:

{
  "mode": "disabled",
  "require_confirmation_above": 5
}

Disabled mode limitations

Even in disabled mode, CRITICAL operations (repository deletion, branch protection removal) always require confirmation. This cannot be overridden.

Confirmation Workflow

When an operation requires confirmation, you’ll receive a confirmation token.

1. Initial request triggers confirmation

   User: "Delete the webhook with ID 123 from my-repo"

2. Server generates confirmation token

   {
     "status": "confirmation_required",
     "operation": "github_delete_webhook",
     "risk_level": "HIGH",
     "parameters": {
       "owner": "username",
       "repo": "my-repo",
       "hook_id": 123
     },
     "token": "7a8f3b2c1d9e4a6b5c8d7e9f2a3b4c5d",
     "expires_at": "2024-02-10T14:35:00Z",
     "warning": "This will permanently remove the webhook. The endpoint will no longer receive events from this repository.",
     "rollback_command": "github_create_webhook with same configuration"
   }

3. User confirms with token

   User: "Confirm deletion with token 7a8f3b2c1d9e4a6b5c8d7e9f2a3b4c5d"

4. Server validates and executes

   {
     "status": "success",
     "operation": "github_delete_webhook",
     "hook_id": 123,
     "message": "Webhook deleted successfully"
   }

Token Properties

• Single-use: Token is invalidated after first use (success or failure)
• 5-minute expiration: Request new token if expired
• SHA256 hash: Cryptographically secure random token
• Operation-specific: Token is tied to exact operation and parameters

Token in parameters

Include the token in the confirmation_token parameter:

{
  "owner": "username",
  "repo": "my-repo",
  "hook_id": 123,
  "confirmation_token": "7a8f3b2c1d9e4a6b5c8d7e9f2a3b4c5d"
}

Dry-Run Mode

Preview destructive operations before execution.

How It Works

1. Set dry_run: true in operation parameters
2. Server simulates operation without making changes
3. Returns preview of what would happen
4. Execute with dry_run: false to apply changes

Example: Repository Settings Update

// Dry-run request
{
  "owner": "username",
  "repo": "my-project",
  "name": "renamed-project",
  "private": true,
  "dry_run": true
}

Response:

{
  "status": "dry_run",
  "operation": "github_update_repo_settings",
  "changes": {
    "name": {
      "from": "my-project",
      "to": "renamed-project",
      "warning": "Repository URL will change. Update all clones and CI/CD configs."
    },
    "private": {
      "from": false,
      "to": true,
      "warning": "Repository will become private. Public forks may be affected."
    }
  },
  "estimated_impact": "Medium - URL change requires updates to external systems",
  "reversible": true
}

Default Dry-Run

Some operations default to dry_run: true:

• Repository deletion
• Branch protection removal
• Repository settings changes

Set dry_run: false explicitly to execute.

Audit Logging

All administrative operations are logged to a JSON audit file.

Log Entry Format

{
  "timestamp": "2024-02-10T14:30:00Z",
  "operation": "github_delete_webhook",
  "risk_level": "HIGH",
  "user": "claude-desktop-user",
  "parameters": {
    "owner": "username",
    "repo": "my-project",
    "hook_id": 123
  },
  "result": "success",
  "confirmation_token_used": "7a8f3b2c***",
  "rollback_command": "github_create_webhook --url https://... --events push,pull_request",
  "execution_time_ms": 234
}

Automatic Rotation

Audit logs rotate automatically:

• Max size: 10MB per file (configurable)
• Backups kept: 5 rotated files (configurable)
• Naming: mcp-admin-audit.log, mcp-admin-audit.log.1, etc.

Configuration:

{
  "audit_log_path": "./mcp-admin-audit.log",
  "audit_log_max_size_mb": 10,
  "audit_log_max_backups": 5
}

Reading Audit Logs

Logs are newline-delimited JSON (NDJSON), one operation per line.

Parse with jq:

# Show all CRITICAL operations
cat mcp-admin-audit.log | jq 'select(.risk_level == "CRITICAL")'

# Operations in last hour
cat mcp-admin-audit.log | jq 'select(.timestamp > (now - 3600 | todate))'

# Failed operations
cat mcp-admin-audit.log | jq 'select(.result != "success")'

Sensitive Data Redaction

Audit logs automatically redact sensitive parameters:

• secret (webhook secrets)
• token (API tokens)
• password (any password fields)

Redacted values appear as [REDACTED] in logs.

Configuration Reference

Create safety.json in the server directory:

{
  "mode": "moderate",
  "enable_audit_log": true,
  "require_confirmation_above": 3,
  "audit_log_path": "./mcp-admin-audit.log",
  "audit_log_max_size_mb": 10,
  "audit_log_max_backups": 5,
  "enable_auto_backup": false,
  "backup_path": "./backups",
  "token_expiration_minutes": 5
}

Option	Type	Default	Description
mode	string	"moderate"	Safety mode (strict/moderate/permissive/disabled)
enable_audit_log	boolean	true	Enable JSON audit logging
require_confirmation_above	number	3	Risk level requiring confirmation (1-4)
audit_log_path	string	"./mcp-admin-audit.log"	Audit log file path
audit_log_max_size_mb	number	10	Max size before rotation (MB)
audit_log_max_backups	number	5	Number of rotated logs to keep
enable_auto_backup	boolean	false	Auto-backup before destructive ops
backup_path	string	"./backups"	Backup directory
token_expiration_minutes	number	5	Confirmation token lifetime

Default Configuration

If safety.json doesn’t exist, the server uses:

• Mode: moderate
• Audit logging: enabled
• Confirmation requirement: HIGH+ (level 3)
• Token expiration: 5 minutes

Best Practices

For Personal Projects

{
  "mode": "permissive",
  "enable_audit_log": true
}

Only confirms CRITICAL operations. Audit log provides accountability.

For Team Repositories

{
  "mode": "moderate",
  "enable_audit_log": true,
  "require_confirmation_above": 3
}

Confirms HIGH+ operations. Balances safety and productivity.

For Production Systems

{
  "mode": "strict",
  "enable_audit_log": true,
  "require_confirmation_above": 2,
  "enable_auto_backup": true
}

Maximum protection. Confirms MEDIUM+ operations with automatic backups.

Security Considerations

Validation Layers

Beyond risk classification, all operations undergo:

1. Parameter validation: Prevents path traversal, command injection
2. SSRF prevention: Validates webhook URLs against private IP ranges
3. GitHub permissions: Token must have appropriate scopes
4. Repository access: User must have admin access for admin tools

Threat Model

The safety system helps with:

• Accidental destructive actions by users
• Misunderstood operation consequences
• Typos in critical parameters
• Scripts running without explicit authorization

The safety system does not protect against:

• Malicious users with valid tokens
• Compromised GitHub tokens (use expiration and rotation)
• Social engineering attacks

Token Security

Confirmation tokens are:

• SHA256-hashed random values (256-bit entropy)
• Single-use only
• Short-lived (5 minutes default)
• Operation-specific (can’t be reused for different operation)

Troubleshooting

”Confirmation token expired”

Tokens expire after 5 minutes. Request a new token by re-attempting the operation.

”Invalid confirmation token”

Possible causes:

• Token already used
• Token from different operation
• Typo in token string

Request new token.

”Safety config validation failed”

safety.json has syntax errors. Validate JSON syntax or delete file to use defaults.

”Audit log rotation failed”

Insufficient disk space or permission issues. Check:

• Available disk space
• Write permissions on audit log directory

Responsible use

Select a safety mode that matches your environment, review parameters before confirming, and keep tokens secure. We are not responsible for misuse or resulting damage.