Security

MateClaw includes several security layers: JWT authentication, ToolGuard (tool execution approval), FileGuard (file access control), AuditLog (security audit logging), and skill content scanning.

JWT Authentication

How It Works

MateClaw uses JSON Web Tokens (JWT) for API authentication:

1. The user sends credentials to /api/v1/auth/login
2. The server validates the credentials and returns a JWT
3. All subsequent requests include the JWT in the Authorization header
4. The server validates the token on each request

Login

curl -X POST http://localhost:18088/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

Response:

{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 86400
  }
}

Using the Token

Include the token in every API request:

curl http://localhost:18088/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Sliding Window Renewal

MateClaw implements sliding-window token renewal:

• When a token is within 25% of its expiry time, the server issues a new token in the response header X-New-Token
• The frontend automatically picks up the new token and replaces the old one
• This prevents users from being logged out during active sessions

Configuration

mateclaw:
  auth:
    jwt:
      secret: your-secret-key-must-be-at-least-32-characters-long
      expiration: 86400000    # 24 hours in milliseconds
      sliding-window: true

WARNING

Change the default JWT secret in production. The secret must be at least 32 characters.

Unified Error Handling

Status Code	Meaning	Response
401	Token missing, expired, or invalid	{"code": 401, "message": "Unauthorized"}
403	Valid token but insufficient permissions	{"code": 403, "message": "Forbidden"}

The frontend handles both codes uniformly -- redirecting to the login page and clearing stored tokens.

Default Credentials

MateClaw ships with a default admin account:

Field	Value
Username	admin
Password	admin123

DANGER

Change the default password immediately in production by updating the mate_user table or through the Settings page.

Spring Security Configuration

MateClaw configures Spring Security with:

• Stateless sessions -- No server-side session; all state is in the JWT
• Public endpoints -- /api/v1/auth/login, /h2-console/**, /swagger-ui/**
• Protected endpoints -- All other /api/v1/** routes require authentication
• CSRF disabled -- Not needed for stateless JWT authentication

ToolGuard

ToolGuard prevents agents from executing dangerous tools without user approval.

How It Works

Agent requests tool call
        |
        v
  Is tool in dangerous list?
        |
   +----+----+
   No        Yes
   |         |
   v         v
Execute   Pause and request
tool      user approval
              |
         +----+----+
      Approved   Rejected
         |         |
         v         v
      Execute   Notify agent
      tool      of rejection

Configuration

mateclaw:
  tool:
    guard:
      enabled: true
      dangerous-tools:
        - ShellExecuteTool
        - WriteFileTool
        - EditFileTool
        - SkillScriptTool
        - BrowserUseTool

Approval Flow in the UI

When ToolGuard pauses execution:

1. The chat interface shows an approval card with the tool name and parameters
2. The user can review what the agent wants to do
3. Clicking "Approve" resumes execution
4. Clicking "Reject" sends a rejection message back to the agent

Programmatic Approval

For automated workflows, you can configure auto-approval rules:

mateclaw:
  tool:
    guard:
      auto-approve:
        - tool: ShellExecuteTool
          pattern: "^(ls|cat|grep|find)\\s"   # Safe read-only commands

UI Management

On the Security page in the frontend, you can view and manage ToolGuard configurations, including reviewing configured approval policies, modifying tool approval levels, and browsing approval history.

FileGuard

FileGuard provides file-system-level access control, restricting the scope of file access for agents and tools to prevent unauthorized read/write operations.

How It Works

When a tool or skill requests file system access, FileGuard evaluates the following pipeline:

File access request -> Path normalization -> Allowlist check -> Denylist check -> Allow/Deny

Access Control Rules

Rule	Description
Workspace isolation	Default access restricted to the workspace directory
System path denial	Access to /etc, /usr, /bin, and other system directories is blocked
Sensitive file protection	Access to .ssh, .config, .env, and similar files is blocked
Path traversal prevention	Detects and blocks ../ path traversal attacks
Symlink checking	Detects attempts to bypass path restrictions via symbolic links

Configuration

mateclaw:
  security:
    file-guard:
      enabled: true
      allowed-paths:
        - "${user.dir}/workspace"
        - "${java.io.tmpdir}/mateclaw"
      denied-paths:
        - "/etc"
        - "/usr"
        - "${user.home}/.ssh"
        - "${user.home}/.config"
        - "${user.home}/.env"

UI Management

On the Security page, the FileGuard section provides a visual interface for managing path rules. You can add, edit, and remove allowed and denied path rules.

AuditLog

AuditLog records all security-relevant operations in the system, providing a complete audit trail for security review and incident investigation.

Scope

AuditLog captures the following event types:

Event Type	Description
Tool calls	Tool name, parameters, result, and duration for each tool invocation
ToolGuard approvals	Approval requests, outcomes (approved/rejected), and approver
FileGuard events	File access requests, paths, and outcomes (allowed/denied)
Skill executions	Skill name, parameters, and associated agent
Login events	Successful/failed logins with IP address
Configuration changes	Changes to security-related settings

Log Structure

Each audit log entry contains:

Field	Description
timestamp	When the operation occurred
user_id	The user who performed the operation
action	Operation type
resource	Target of the operation (tool name, file path, skill name)
details	Operation details in JSON format
result	Outcome (success, failure, denied)
ip_address	Source IP address

UI Access

On the Security page, the AuditLog section provides a query interface for browsing audit logs. You can filter by time range, event type, user, and other criteria for security auditing purposes.

Skill Security Scanning

When a custom skill is uploaded, MateClaw scans the SKILL.md content for:

Check	Description
Prompt injection patterns	Attempts to override system prompts
Dangerous tool references	Skills requesting tools not in the allowed list
External URL references	Links to untrusted external resources
Script injection	Embedded scripts or code execution attempts

Skills that fail scanning are flagged and require manual admin approval before activation.

Severity Levels

Level	Description	Action
CRITICAL	Severe security risk	Installation blocked, must be fixed
HIGH	High risk	Warning, requires admin confirmation
MEDIUM	Medium risk	Warning displayed
LOW	Low risk	Logged only
INFO	Informational	Logged only

Security Pages in the UI

The MateClaw frontend provides a unified Security management page that centralizes all security-related features:

• ToolGuard Management: View and configure tool approval policies, browse approval history
• FileGuard Management: Manage file access control rules, view interception records
• AuditLog Viewer: Query and filter audit logs, export log data
• Skill Security Scans: Review security scan reports for installed skills

API Key Security

• API keys (DashScope, Serper, etc.) are stored as environment variables, not in code
• Model provider API keys in the database are encrypted at rest
• API keys are never returned in API responses -- they are masked as sk-****

Network Security

Production Recommendations

Recommendation	Details
Use HTTPS	Place MateClaw behind a reverse proxy (Nginx, Caddy) with TLS
Restrict H2 console	Disable spring.h2.console.enabled in production
Firewall	Only expose port 18080 (or your chosen port)
Rate limiting	Configure rate limiting at the reverse proxy level
Separate DB	Use a dedicated MySQL instance, not H2

Reverse Proxy Example (Nginx)

server {
    listen 443 ssl;
    server_name mateclaw.example.com;

    ssl_certificate /etc/ssl/certs/mateclaw.pem;
    ssl_certificate_key /etc/ssl/private/mateclaw.key;

    location / {
        proxy_pass http://localhost:18080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support
        proxy_buffering off;
        proxy_read_timeout 86400s;
    }
}

Security Best Practices

1. Change default password: Update the admin password immediately after deployment
2. Least privilege: Only enable tools that agents actually need
3. Approve risky operations: Enable manual approval for file write, shell execution, and similar tools
4. Configure FileGuard: Restrict file access scope and protect sensitive directories
5. Review audit logs regularly: Use AuditLog to monitor security-relevant events
6. Review skill scans: Periodically check security scan reports for installed skills
7. Secure API keys: Use environment variables, never hard-code keys
8. Network isolation: Restrict network access for local services like Ollama in production
9. Monitor logs: Watch for anomalous tool calls and access patterns

Security Configuration Reference

mateclaw:
  security:
    jwt:
      secret: ${JWT_SECRET:your-secret-key-at-least-32-chars}
      expiration: 86400          # Token TTL in seconds
      sliding-window-ratio: 0.5  # Renewal trigger threshold
    tool-guard:
      enabled: true
      default-policy: auto_approve
    file-guard:
      enabled: true
      allowed-paths:
        - "${user.dir}/workspace"
      denied-paths:
        - "/etc"
        - "${user.home}/.ssh"
    audit-log:
      enabled: true
      retention-days: 90         # Audit log retention period
    skill:
      security-scan:
        enabled: true
        block-critical: true     # Block installation of skills with critical findings

Next Steps

• Configuration -- JWT and ToolGuard configuration
• Tool System -- Tool details and dangerous tool list
• Skill System -- Skill security scanning details