Skip to content

Gira MCP Server Security Model

The Gira MCP server implements a comprehensive, layered security model designed to provide safe AI agent interaction while maintaining usability. This document covers all security mechanisms, configuration options, and best practices.

🛡️ Security Architecture Overview

The Gira MCP server security model is built on multiple complementary layers:

  1. Working Directory Validation - Restricts operations to authorized Gira projects
  2. Consent Mechanisms - Configurable confirmation for destructive operations
  3. Input Validation & Sanitization - Prevents injection attacks and malformed data
  4. Rate Limiting - Prevents abuse and accidental bulk operations
  5. Audit Logging - Complete operation tracking for transparency
  6. Operation Blocking - Granular control over available functionality
  7. Dry Run Mode - Safe testing without actual changes

🔒 Core Security Mechanisms

Working Directory Protection

Purpose: Ensures all operations are restricted to valid Gira projects within authorized directories.

Implementation: - All file operations are confined to the configured working directory - Path traversal attacks are prevented through path resolution and validation - Only directories containing a .gira folder are considered valid projects - Symbolic links and parent directory references are resolved and validated

Configuration: 

# Set working directory (required)
GIRA_MCP_WORKING_DIRECTORY="/path/to/your/gira/project"

# Optional: Maximum directory traversal depth
GIRA_MCP_MAX_WORKING_DIRECTORY_DEPTH=10

Security Checks: - ✅ Working directory exists and is accessible - ✅ Directory contains a valid .gira project structure - ✅ All file paths resolve within the working directory - ✅ No access to parent directories or arbitrary file system locations

Purpose: Provides configurable confirmation requirements for operations that modify data.

Dry Run Mode: 

# Enable dry run (default: true)
GIRA_MCP_DRY_RUN=true

When enabled: - All operations are simulated without making actual changes - Full validation and processing occurs - Results show what would happen - Perfect for testing and development

Confirmation Requirements: 

# Require explicit confirmation for destructive operations
GIRA_MCP_REQUIRE_CONFIRMATION=true

Operations Requiring Confirmation: | Operation | Reason | Override | |-----------|--------|----------| | create_ticket | Creates new data | Configuration | | update_ticket | Modifies existing data | Configuration | | move_ticket | Changes ticket state | Configuration | | delete_ticket | Permanent data removal | Always required | | bulk_update | Mass changes | Always required | | archive_tickets | Data archival | Always required | | move_tickets_bulk | Mass state changes | Always required |

Input Validation & Sanitization

Purpose: Prevents injection attacks, validates data integrity, and ensures system stability.

ID Validation & Normalization: 

# Ticket IDs are automatically normalized
"123" → "GCM-123"
"gcm-456" → "GCM-456" 
"GCM-789" → "GCM-789"  # Already valid

# Epic IDs are normalized
"1" → "EPIC-001"
"epic-002" → "EPIC-002"
"EPIC-003" → "EPIC-003"  # Already valid

String Input Limits: 

# Maximum string input length (default: 10,000 characters)
GIRA_MCP_MAX_INPUT_LENGTH=10000

# Maximum list input length (default: 1,000 items)
GIRA_MCP_MAX_LIST_LENGTH=1000

Validation Rules: - Ticket IDs: Must match pattern ^[A-Z]+-\d+$ - Epic IDs: Must match pattern ^EPIC-\d+$ - Sprint IDs: Must match pattern ^SPRINT-\d{4}-\d{2}-\d{2}$ - Email addresses: Basic format validation for assignees - Dates: Must be in YYYY-MM-DD format - Enums: Status, priority, type values validated against project configuration

SQL Injection Prevention: - All data access uses parameterized queries - JSON file operations use safe parsing - No dynamic query construction with user input

Rate Limiting

Purpose: Prevents abuse, accidental bulk operations, and system overload.

Rate Limits by Tool Category:

Tool Category Rate Limit Window Rationale
Read Operations 100 calls 60 sec High limit for frequent queries
Ticket CRUD 50 calls 60 sec Moderate limit for normal usage
Search/Filter 20 calls 60 sec Lower limit for expensive operations
Bulk Operations 5 calls 60 sec Very low limit for mass changes
Destructive Operations 2 calls 60 sec Minimal limit for safety

Specific Tool Limits: 

# Query tools (high frequency)
list_tickets: 50 calls/minute
get_ticket: No limit (read-only)
search_tickets: 20 calls/minute

# Creation tools (moderate frequency)
create_ticket: 30 calls/minute
create_epic: 10 calls/minute
create_sprint: 10 calls/minute

# Update tools (moderate frequency)
update_ticket: 30 calls/minute
move_ticket: 30 calls/minute
assign_ticket: 30 calls/minute

# Bulk operations (low frequency)
bulk_update: 5 calls/minute
move_tickets_bulk: 10 calls/minute
archive_tickets: 2 calls/minute

# Analytics (low frequency due to complexity)
get_sprint_metrics: 10 calls/minute
get_enhanced_board_state: 60 calls/minute

Rate Limit Configuration: Rate limits are built into each tool and cannot be disabled for security reasons.

Audit Logging

Purpose: Provides complete transparency and traceability for all MCP operations.

Configuration: 

# Enable audit logging (default: true)
GIRA_MCP_AUDIT_ENABLED=true

# Include parameter details in logs (default: false)
GIRA_MCP_VERBOSE_LOGGING=true

Log Location: - File: gira-mcp-audit.log in the working directory - Format: Structured logging with timestamp, operation, and result - Rotation: Logs rotate automatically to prevent disk space issues

Log Entry Structure: 

2024-02-15 14:30:22 - AUDIT - INFO - OPERATION_START - create_ticket - user:claude
2024-02-15 14:30:22 - AUDIT - INFO - PARAMETERS - {"title": "Fix login bug", "priority": "high"}
2024-02-15 14:30:23 - AUDIT - INFO - OPERATION_SUCCESS - create_ticket - ticket_id:GCM-456
2024-02-15 14:30:23 - AUDIT - INFO - PERFORMANCE - create_ticket - duration:1.2s

Logged Information: - Timestamp: Precise operation timing - Operation: MCP tool name - Parameters: Input parameters (if verbose logging enabled) - Result: Success/failure status - Performance: Operation duration - User Context: AI agent identifier (when available) - Security Events: Rate limit violations, blocked operations

Operation Blocking

Purpose: Allows fine-grained control over which operations are available.

Configuration: 

# Block specific operations (comma-separated)
GIRA_MCP_BLOCKED_OPERATIONS="delete_ticket,archive_tickets,bulk_update"

# Block entire categories
GIRA_MCP_BLOCKED_OPERATIONS="ticket.delete,ticket.archive,epic.delete"

# Block destructive operations entirely
GIRA_MCP_BLOCKED_OPERATIONS="delete_ticket,archive_tickets,bulk_update,move_tickets_bulk"

Blockable Operations: - Individual Tools: Any tool can be blocked by name - Operation Categories: Block entire families of operations - Destructive Operations: Special category for data-changing operations

Common Blocking Scenarios: 

# Read-only mode
GIRA_MCP_BLOCKED_OPERATIONS="create_ticket,update_ticket,move_ticket,delete_ticket,bulk_update,archive_tickets"

# No bulk operations
GIRA_MCP_BLOCKED_OPERATIONS="bulk_update,move_tickets_bulk,archive_tickets"

# No ticket deletion
GIRA_MCP_BLOCKED_OPERATIONS="delete_ticket,archive_tickets"

🚦 Security Levels & Configurations

# Working directory restriction
GIRA_MCP_WORKING_DIRECTORY="/secure/path/to/project"

# Dry run disabled for actual operations
GIRA_MCP_DRY_RUN=false

# All confirmations required
GIRA_MCP_REQUIRE_CONFIRMATION=true

# Full audit logging
GIRA_MCP_AUDIT_ENABLED=true
GIRA_MCP_VERBOSE_LOGGING=true

# Strict input limits
GIRA_MCP_MAX_INPUT_LENGTH=5000
GIRA_MCP_MAX_LIST_LENGTH=100

# Block dangerous operations
GIRA_MCP_BLOCKED_OPERATIONS="delete_ticket,archive_tickets"

# Working directory restriction
GIRA_MCP_WORKING_DIRECTORY="/team/project/path"

# Dry run disabled
GIRA_MCP_DRY_RUN=false

# Confirmations for destructive operations only
GIRA_MCP_REQUIRE_CONFIRMATION=true

# Standard audit logging
GIRA_MCP_AUDIT_ENABLED=true
GIRA_MCP_VERBOSE_LOGGING=false

# Standard input limits
GIRA_MCP_MAX_INPUT_LENGTH=10000
GIRA_MCP_MAX_LIST_LENGTH=1000

# Block only extremely dangerous operations
GIRA_MCP_BLOCKED_OPERATIONS="delete_ticket"

Level 3: Development Security (For Testing)

# Working directory restriction
GIRA_MCP_WORKING_DIRECTORY="/dev/test/project"

# Dry run enabled for safety
GIRA_MCP_DRY_RUN=true

# No confirmations needed
GIRA_MCP_REQUIRE_CONFIRMATION=false

# Full audit logging for debugging
GIRA_MCP_AUDIT_ENABLED=true
GIRA_MCP_VERBOSE_LOGGING=true

# Higher input limits for testing
GIRA_MCP_MAX_INPUT_LENGTH=20000
GIRA_MCP_MAX_LIST_LENGTH=2000

# No operations blocked
GIRA_MCP_BLOCKED_OPERATIONS=""

🔍 Security Monitoring & Analysis

Real-Time Security Monitoring

Rate Limit Violations: 

2024-02-15 14:35:10 - AUDIT - WARNING - RATE_LIMIT_EXCEEDED - list_tickets - limit:50/60s

Blocked Operations: 

2024-02-15 14:35:15 - AUDIT - ERROR - OPERATION_BLOCKED - delete_ticket - reason:configured_block

Invalid Input Attempts: 

2024-02-15 14:35:20 - AUDIT - WARNING - VALIDATION_ERROR - create_ticket - error:invalid_title_length

Path Traversal Attempts: 

2024-02-15 14:35:25 - AUDIT - ERROR - SECURITY_VIOLATION - file_access - path:../../../etc/passwd

Security Analytics

Performance Monitoring: - Track operation response times - Identify unusually slow operations - Monitor resource usage patterns

Usage Pattern Analysis: - Detect unusual operation sequences - Identify potential automated abuse - Monitor bulk operation usage

Error Pattern Analysis: - Track validation failures - Identify repeated security violations - Monitor rate limit patterns

🛠️ Security Best Practices

For System Administrators

Working Directory Setup: 1. Use dedicated directories for each Gira project 2. Set appropriate file permissions (read/write for MCP user only) 3. Regular backup of audit logs and project data 4. Monitor disk space for log files

Configuration Management: 1. Use environment variables for sensitive configuration 2. Store configurations in secure files with restricted permissions 3. Regular security reviews of configuration settings 4. Document security decisions and rationale

Monitoring & Alerting: 1. Set up log monitoring for security events 2. Configure alerts for rate limit violations 3. Regular audit log review for suspicious patterns 4. Performance monitoring for resource usage

For AI Agent Users

Safe Usage Patterns: 1. Start with dry run mode to understand operation effects 2. Use confirmations for destructive operations 3. Review audit logs regularly for unexpected operations 4. Limit bulk operations to necessary minimums

Data Protection: 1. Verify working directory before starting operations 2. Use version control for Gira project data 3. Regular backups of important project data 4. Test operations in non-production environments first

Error Handling: 1. Understand error messages and their security implications 2. Don't bypass security measures by modifying configurations 3. Report security issues through proper channels 4. Keep audit logs for troubleshooting

🚨 Security Incident Response

Immediate Response Steps

  1. Stop MCP Server: Immediately stop the MCP server if security breach suspected
  2. Preserve Evidence: Copy audit logs and system logs before any changes
  3. Assess Impact: Review audit logs to understand scope of potential breach
  4. Secure Environment: Change any compromised credentials or access keys

Investigation Process

  1. Audit Log Analysis: Review complete operation history
  2. File System Check: Verify integrity of Gira project data
  3. Configuration Review: Check for unauthorized configuration changes
  4. Network Analysis: Review network access patterns if applicable

Recovery Steps

  1. Data Restoration: Restore from known-good backups if necessary
  2. Security Hardening: Implement additional security measures
  3. Configuration Update: Update security settings based on lessons learned
  4. Monitoring Enhancement: Improve monitoring and alerting systems

❓ Security FAQ

Common Questions

Q: Can the MCP server access files outside the working directory? A: No. All file operations are strictly confined to the configured working directory and must be within a valid Gira project.

Q: What happens if I try to perform a blocked operation? A: The operation is rejected immediately with a clear error message, and the attempt is logged in the audit log.

Q: Are my API calls private? A: Operation names and results are logged. Parameters are only logged if verbose logging is enabled. Configure logging according to your privacy requirements.

Q: Can I disable all security measures? A: No. Core security measures like working directory validation cannot be disabled. Other measures can be configured but disabling them is not recommended.

Q: How do I know if someone is abusing the MCP server? A: Monitor the audit logs for unusual patterns, rate limit violations, and blocked operation attempts.

Q: What should I do if I see security warnings in the logs? A: Investigate immediately. Security warnings indicate potential security issues that should be addressed.

Troubleshooting Security Issues

"Permission denied" errors: - Check working directory permissions - Verify Gira project structure exists - Ensure no path traversal in file operations

Rate limit exceeded: - Wait for rate limit window to reset - Reduce operation frequency - Consider if bulk operations are being overused

Operation blocked: - Check GIRA_MCP_BLOCKED_OPERATIONS configuration - Verify operation is needed and safe - Use alternative operations if available

Validation errors: - Check input format and length limits - Verify ID formats match expected patterns - Review parameter types and constraints

For configuration details, see Configuration Reference. For installation and setup, see Installation Guide. For operational usage, see the Tool References.