Mockarty Administration Guide

This guide covers everything an administrator needs to configure after the first launch of Mockarty. It assumes you have already installed and deployed Mockarty following the Installation & Deployment guide.

About URLs in examples: All examples use localhost:5770 as the default Mockarty address. If your instance runs on a remote server, replace localhost:5770 with its actual address (e.g. https://mockarty.company.com or http://192.168.1.50:5770). See Tips & Useful Features for details.

Table of Contents

1. First Launch
2. Authentication Configuration
3. User Management
4. System Roles
5. Namespace Management
6. Namespace Roles
7. Assigning Users to Namespaces
8. Email Notifications Setup
9. Backup and Restore
10. Cleanup Policies
11. Audit Logs
12. LLM / AI Assistant Configuration
13. Security Best Practices

First Launch

When you start Mockarty for the first time, the following happens automatically:

• Database migrations are applied, creating all required tables and indexes.
• A default namespace called sandbox is created.
• A built-in admin account is created with default credentials.

Default Credentials

Warning: Change the default password immediately after your first login. Using default credentials in production is a critical security risk.

Trial License: On first launch, Mockarty starts with a 7-day trial license. Trial limits: 3 users (excluding admin), 10 mocks, sandbox namespace only. To unlock full capabilities, apply a license key in Administration → License.

Accessing the Web UI

Open your browser and navigate to:

http://localhost:5770/ui/

You will see the login page. Enter the default credentials to log in.

Changing the Default Password

1. Log in with admin / admin.
2. Navigate to Settings (gear icon in the sidebar).
3. Go to the Profile section.
4. Click Change Password.
5. Enter a new strong password (minimum 8 characters).
6. Click Save.

Authentication Configuration

Mockarty supports multiple authentication methods. The core auth settings are controlled by environment variables, while external identity providers (OAuth, LDAP) are configured through the Admin Panel UI with hot-reload support — no restart required.

Key Concepts

If you are new to authentication terminology, here is a quick reference:

• OAuth 2.0 — A standard protocol that lets users log in to Mockarty using their existing account from another service (Google, GitHub, etc.) instead of creating a separate password. You have probably seen “Sign in with Google” buttons — that is OAuth.
• LDAP / Active Directory — A directory service commonly used in corporate environments to store user accounts centrally. If your company uses Windows domain logins, it likely runs Active Directory, which speaks the LDAP protocol.
• SAML — An enterprise Single Sign-On (SSO) protocol used by services like Okta, Azure AD, and OneLogin. It allows users to log in once and access multiple applications without re-entering credentials.
• RBAC — Role-Based Access Control. Instead of granting permissions to individual users, you assign them roles (e.g., Owner, User, Viewer), and each role has a predefined set of permissions.
• 2FA / MFA — Two-Factor (or Multi-Factor) Authentication. After entering your password, you must provide a second proof of identity, such as a code from an authenticator app or email.

Authentication Mode (AUTH_MODE)

The AUTH_MODE environment variable controls the overall authentication strategy:

Set it in your environment or .env file:

AUTH_MODE=full   # default, multi-user server deployment
AUTH_MODE=local  # single-user mode (no login screen)

Base URL for OAuth Redirects (AUTH_BASE_URL)

When using OAuth providers, Mockarty needs to know its own public URL so it can construct correct redirect URIs (the URL the provider sends the user back to after login).

AUTH_BASE_URL=https://mockarty.yourcompany.com

Important: If AUTH_BASE_URL does not match the redirect URI registered with the OAuth provider, login will fail with a “redirect_uri_mismatch” error.

First Admin Account

On first startup, Mockarty creates an admin user using these environment variables:

If the default admin/admin credentials are used, the system will force a password change on the first login.

Tip: For automated deployments, set custom values to avoid the password-change prompt:

FIRST_ADMIN_LOGIN=myadmin
FIRST_ADMIN_PASSWORD=MyStr0ngP@ssword!
FIRST_ADMIN_EMAIL=admin@yourcompany.com

Session Expiration (AUTH_SESSION_EXPIRATION)

Controls how long a user session lasts before requiring re-authentication:

AUTH_SESSION_EXPIRATION=48  # sessions last 2 days

Local Authentication (Default)

When no external identity provider is configured, Mockarty uses its built-in local authentication system. Users log in with a username and password stored in the Mockarty database.

Password requirements:

• Minimum 8 characters

OAuth 2.0 Setup

OAuth 2.0 allows users to log in with their existing accounts from external services instead of creating a separate Mockarty password. Mockarty supports the following OAuth providers:

• Google
• Yandex
• VK
• GitHub
• GitLab
• Generic / Custom OAuth — any OAuth 2.0 compatible provider

Configuring OAuth Providers via Admin Panel

All OAuth providers are configured through the Admin Panel UI. No environment variables are needed for individual providers.

1. Navigate to Admin Panel > Identity Providers.
2. Click Add Identity Provider.
3. Select the provider type (e.g., Google, GitHub, GitLab, Generic).
4. Fill in the required fields:
   • Client ID — Obtained from the provider’s developer console.
   • Client Secret — Obtained from the provider’s developer console.
   • For Generic/Custom providers, you will also need to fill in: Authorization URL, Token URL, UserInfo URL, and Scopes.
5. Toggle Enabled to activate the provider.
6. Click Save.

Hot-reload: Changes take effect immediately. You do not need to restart Mockarty after adding, editing, or removing an identity provider.

Redirect URI: When registering your application in the provider’s developer console, use the following redirect URI:

{AUTH_BASE_URL}/api/v1/auth/oauth/callback

For example: https://mockarty.yourcompany.com/api/v1/auth/oauth/callback

When OAuth providers are enabled, the login page automatically displays “Sign in with…” buttons for each active provider.

LDAP / Active Directory

LDAP (Lightweight Directory Access Protocol) allows Mockarty to authenticate users against your organization’s existing user directory, such as Microsoft Active Directory. This means users can log in with the same credentials they use for their corporate network.

Configuring LDAP via Admin Panel

LDAP is configured through the Admin Panel UI, just like OAuth providers.

1. Navigate to Admin Panel > Identity Providers.
2. Click Add Identity Provider.
3. Select LDAP / Active Directory as the type.
4. Fill in the connection details:
   • LDAP URL — Your directory server address (e.g., ldap://ldap.example.com:389 or ldaps://ldap.example.com:636 for TLS).
   • Base DN — The starting point for user searches (e.g., dc=example,dc=com).
   • Bind DN — The account used to connect and search the directory (e.g., cn=admin,dc=example,dc=com).
   • Bind Password — Password for the bind account.
   • User Filter — LDAP filter to locate users. Use %s as a placeholder for the username (e.g., (sAMAccountName=%s) for Active Directory, (uid=%s) for OpenLDAP).
5. Click Test Connection to verify that Mockarty can reach your directory server and authenticate with the bind credentials.
6. Toggle Enabled and click Save.

Hot-reload: Like OAuth, LDAP configuration changes take effect immediately without restarting Mockarty.

When LDAP is enabled, users can log in with their directory credentials. On first login, a Mockarty account is created automatically with the User system role. The administrator can then assign namespace roles as needed.

SAML SSO

Mockarty supports SAML 2.0 for Single Sign-On integration with enterprise identity providers (Okta, Azure AD, OneLogin, etc.).

Configuration is done through the Admin Panel:

1. Navigate to Admin Panel > Authentication > SAML.
2. Upload or paste the Identity Provider (IdP) metadata XML.
3. Copy the Mockarty Service Provider (SP) metadata URL and register it with your IdP.
4. Configure attribute mapping (email, display name, groups).
5. Enable SAML authentication.

Two-Factor Authentication (2FA)

Mockarty supports two types of two-factor authentication:

TOTP (Time-based One-Time Passwords):

• Works with any authenticator app (Google Authenticator, Authy, Microsoft Authenticator, etc.)
• Users enable it from Settings > Security > Two-Factor Authentication.
• A QR code is displayed for scanning with the authenticator app.
• Recovery codes are provided for backup access.

Email codes:

• One-time codes sent to the user’s registered email address.
• Requires email notifications to be configured (see Email Notifications Setup).
• Users enable it from Settings > Security > Two-Factor Authentication.

Managing 2FA for users:

Administrators can manage 2FA on a per-user basis:

• Disable 2FA for a user: Navigate to Admin Panel > Users, select the user, and click Disable 2FA. This removes both TOTP and email 2FA for that user.
• Recommendation: Strongly recommend (or require through organizational policy) that all Admin and Support role users enable 2FA for their accounts.

Note: 2FA is enabled by individual users in their own Settings > Security > Two-Factor Authentication page. There is no global enforcement toggle — 2FA adoption is managed through organizational policy.

User Management

Creating Users

1. Navigate to Admin Panel > Users.
2. Click Create User.
3. Fill in the required fields:
   • Username — Unique login name.
   • Email — Email address (used for notifications and password resets).
   • Password — Initial password (user can change it later).
   • System Role — Select from Admin, Support, Auditor, or User (see System Roles).
4. Click Create.

Setting Passwords and Emails

• To reset a user’s password: Admin Panel > Users > (select user) > Reset Password.
• To change a user’s email: Admin Panel > Users > (select user) > Edit > Email.
• Password reset links can be sent via email if email notifications are configured.

Disabling / Enabling Accounts

Disabled accounts cannot log in, but their data and namespace assignments are preserved.

1. Navigate to Admin Panel > Users.
2. Find the user in the list.
3. Click the toggle switch next to their name to disable or enable the account.

Deleting Users

1. Navigate to Admin Panel > Users.
2. Find the user in the list.
3. Click Delete.
4. Confirm the deletion.

Note: Deleting a user removes their account and all namespace role assignments. Mocks and other resources created by the user are preserved.

User Self-Registration

When OAuth or LDAP is enabled, users can register themselves by logging in through the external identity provider. A Mockarty account is created automatically with the User system role. The administrator can then assign namespace roles as needed.

System Roles

Mockarty has four system-level roles that determine what a user can access across the entire platform.

Role Descriptions

Admin
Full system access. Admins can manage all users, all namespaces, system settings, audit logs, backups, email configuration, LLM profiles, telemetry, and database health. This role should be limited to a small number of trusted people.

Support
Full access to namespace resources (mocks, stores, API tests, fuzzing, recorder, collections) across all namespaces. In the Admin Panel, Support users can view user accounts, reset passwords, and view audit logs, but cannot create or delete users, change system settings, or access sensitive configuration. Support users cannot create or delete namespaces.

Auditor
Read-only access to audit logs and system metrics. Auditors cannot modify any resources and cannot export audit logs. In the sidebar, they see: Dashboard, Mocks (view only), Test Runs, Recorder (view only), Fuzzing (view only), Utils, Settings (view only), and Admin Panel (audit logs view only).

User
Standard user account. Permissions are determined entirely by namespace role assignments (see Namespace Roles). Users have no access to the Admin Panel.

Permissions Matrix

Namespace Management

What Is a Namespace

A namespace is an isolated workspace within Mockarty. Each namespace contains its own:

• Mocks and routes
• Global, Chain, and Mock stores
• API test collections and environments
• Test run results
• Recorder sessions
• Fuzzing configurations
• API tokens

Namespaces provide separation between teams, services, or environments. Resources in one namespace are invisible to users of another namespace (unless they have roles in both).

Creating Namespaces

Via Admin Panel:

1. Navigate to Admin Panel > Namespaces.
2. Click Create Namespace.
3. Enter a name and optional description.
4. Click Create.

Via Settings page:

1. Navigate to Settings > Namespaces (visible to Admin users).
2. Click Create Namespace.
3. Enter a name and optional description.
4. Click Create.

Naming Conventions and Best Practices

Choose a naming convention that fits your organization:

Tips:

• Use lowercase names with hyphens (e.g., user-service).
• Keep names short but descriptive.
• Avoid generic names like test or temp for permanent namespaces.
• Document your naming convention so all teams follow it consistently.

Default Namespace

The sandbox namespace is created automatically on first launch. It cannot be deleted. All users have access to the default namespace unless explicitly removed.

Deleting / Restoring Namespaces

1. Navigate to Admin Panel > Namespaces.
2. Find the namespace and click Delete.
3. Confirm the deletion.

Warning: Deleting a namespace removes all mocks, stores, test collections, and other resources within it. This action is irreversible.

Namespace Roles

Within each namespace, users can have one of three roles that control what they can do with namespace resources.

Role Descriptions

Owner
Full control over the namespace. Owners can manage namespace settings, add or remove users, and perform all operations on resources (mocks, stores, collections, tests). Namespace Owners cannot delete the namespace — only users with the Admin or Support system role can delete namespaces.

User
Can create, edit, and delete mocks, stores, collections, and run tests. Users cannot manage namespace settings or add/remove users.

Viewer
Read-only access to all namespace resources. Viewers can browse mocks, view test results, and see store values, but cannot create, edit, or delete anything.

Namespace Capabilities Matrix

Assigning Users to Namespaces

Adding a User to a Namespace

1. Switch to the target namespace using the namespace selector in the sidebar.
2. Navigate to Settings > Users.
3. Click Add User.
4. Select the user account from the dropdown list.
5. Choose a role: Owner, User, or Viewer.
6. Click Add.

Changing a User’s Namespace Role

1. Navigate to Settings > Users within the target namespace.
2. Find the user in the list.
3. Click the role dropdown next to their name.
4. Select the new role.
5. The change takes effect immediately.

Removing a User from a Namespace

1. Navigate to Settings > Users within the target namespace.
2. Find the user in the list.
3. Click Remove.
4. Confirm the action.

Note: Removing a user from a namespace does not delete their account. They simply lose access to that namespace’s resources.

Email Notifications Setup

Email notifications enable password resets, 2FA code delivery, invite links, and test run notifications.

Enabling Email

Email settings are configured through the Admin Panel UI (no restart required):

1. Navigate to Admin Panel > Email Settings.
2. Fill in the SMTP connection details:
   • SMTP Host — your SMTP server (e.g., smtp.gmail.com)
   • SMTP Port — typically 587 for STARTTLS or 465 for Implicit TLS
   • Username / Password — SMTP authentication credentials
   • From Address — the sender email address shown to recipients
   • From Name — the sender display name (e.g., Mockarty)
   • Reply-To — optional reply-to address
3. Toggle Enabled and click Save.

Alternative: environment variables. SMTP settings can also be provided via environment variables at startup (EMAIL_ENABLED, SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, EMAIL_FROM, EMAIL_FROM_NAME, EMAIL_REPLY_TO, SMTP_USE_IMPLICIT_TLS). See the Installation & Deployment Guide for the full reference. UI settings take precedence over environment variables after the first save.

Testing Email Configuration

1. Navigate to Admin Panel > Email Settings.
2. Click Send Test Email.
3. Enter a recipient email address.
4. Click Send.
5. Verify the test email arrives in the recipient’s inbox.

Custom Email Templates

Mockarty uses built-in HTML templates for all email notifications. You can customize them:

1. Navigate to Admin Panel > Email tab, then switch to the Templates sub-tab.
2. Select the template to customize (e.g., “Password Reset”, “2FA Code”, “Welcome”, “Invite”, “Email Verify”).
3. Edit the subject line, HTML template, and plain text template. Available variables are listed on the page.
4. Click Save.
5. Use Preview to see how the email will look.
6. Use Reset to Default to restore the built-in template.

What Gets Sent

Backup and Restore

Mockarty has a built-in backup system that uses pg_dump / pg_restore for PostgreSQL and file copy for SQLite to create and restore database backups. Backups are managed through the Admin Panel or API.

Automatic Backups

Mockarty runs scheduled backups automatically. The default schedule is daily at 2:00 AM (configurable via cron expression). In distributed deployments, backups run only on the leader node to avoid duplicates.

Configuring Backup

1. Navigate to Admin Panel > Backup.
2. Click Create Backup Config (or edit the default config).
3. Configure:
   • Schedule — Cron expression (e.g., 0 0 2 * * * for daily at 2 AM).
   • Retention — Number of days to keep old backups (0 = unlimited).
   • Compression — Enable compression for smaller backup files.
   • Format — custom (recommended, supports pg_restore), plain (SQL text), tar, or directory.
   • Include schema / Include data — Choose what to include.
4. Toggle Enabled and click Save.

Manual Backup

Via Admin Panel:

1. Navigate to Admin Panel > Backup.
2. Click Create Backup.
3. Wait for the backup to complete.
4. Click Download to save the backup file.

Via API:

# Create a backup
curl -X POST http://localhost:5770/api/v1/admin/backups/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config_id": "your-config-id"}'

# Download the backup
curl http://localhost:5770/api/v1/admin/backups/download?path=backup_file.dump \
  -H "Authorization: Bearer $TOKEN" \
  -o backup.dump

Restoring from Backup

Via Admin Panel:

1. Navigate to Admin Panel > Backup.
2. Click Restore.
3. Upload the backup file.
4. Confirm the restore operation.
5. Wait for the process to complete. The license cache will be reloaded automatically.

Via API:

# Restore from uploaded file
curl -X POST http://localhost:5770/api/v1/admin/backups/restore-from-file \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@backup.dump"

Warning: Restoring a backup replaces all current data. This operation cannot be undone.

What Is Included in a Backup

• Complete database (all mocks, stores, users, namespaces, test results, audit logs, configurations)
• Backup format depends on your settings (custom format is recommended for fastest restore)

Docker and Kubernetes

The official Mockarty Docker image includes postgresql-client (pg_dump, pg_restore, psql), so backups work out of the box in Docker and Kubernetes environments.

Mount a persistent volume for the backup storage directory:

docker run -v /host/path/data:/app/data mockarty:latest

SQLite Backups

For SQLite deployments, Mockarty creates backups by copying the database file after a WAL checkpoint. The same Admin Panel interface is used — no additional tools are required.

Cleanup Policies

Cleanup policies control how long historical data is retained. Configuring these prevents the database from growing indefinitely.

Configuring Cleanup

Navigate to Admin Panel > Cleanup or Settings > Cleanup within a namespace.

Available Policies

Expired mock handling options:

• Archive — Mark expired mocks as inactive. They stop matching requests but remain visible in the UI for reference.
• Auto-delete — Permanently remove expired mocks after a configurable grace period.
• Do nothing — Leave expired mocks as-is (not recommended for production).

Audit Logs

Audit logs provide a detailed record of all significant actions performed in the system.

What Is Logged

• Authentication events — User logins (success and failure), logouts, 2FA challenges.
• Mock operations — Create, update, delete, import, export.
• Namespace changes — Create, delete, user role assignments.
• Admin actions — User management, system settings changes, backup/restore.
• API token usage — Token creation, deletion, and usage patterns.
• Store operations — Global store modifications.

Viewing Audit Logs

1. Navigate to Admin Panel > Audit Logs.
2. Browse the chronological list of events.

Filtering

Use the filter controls at the top of the page:

• User — Filter by specific user account.
• Event type — Filter by action type (login, mock.create, namespace.delete, etc.).
• Date range — Specify start and end dates.
• Namespace — Filter by namespace (for namespace-scoped events).

Exporting Audit Logs

1. Apply desired filters.
2. Click Export.
3. Choose format:
   • CSV — Comma-separated values, suitable for spreadsheet analysis.
   • JSON — Structured data, suitable for programmatic processing.
4. The file downloads to your browser.

LLM / AI Assistant Configuration

Mockarty includes an AI assistant (Agent Chat) that helps users create mocks, troubleshoot issues, and explore the system using natural language.

Enabling the AI Assistant

Set the following environment variable:

ENABLE_LLM=true

MCP Server

If you want to expose Mockarty tools via MCP (Model Context Protocol) for external AI agents, enable the built-in MCP server:

ENABLE_MCP=true

Agent Concurrency

The AI agent subsystem (ADK) controls how many agent tasks can run simultaneously and how long sessions last:

Default Configuration

When enabled without additional configuration, Mockarty connects to a local Ollama instance:

Local Ollama (for Developers)

Ollama lets you run open-source LLMs locally. This is useful for development and testing when you do not want to use a cloud LLM provider.

Install Ollama:

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

Start Ollama and pull a model:

# Start the Ollama server
ollama serve &

# Pull a model (choose size based on available RAM)
ollama pull qwen3:0.6b   # ~1 GB RAM — smallest, fast
ollama pull qwen3:1.7b   # ~2 GB RAM — balanced (default)
ollama pull qwen3:4b     # ~3.5 GB RAM — better quality

Configure Mockarty to use Ollama:

Set ENABLE_LLM=true and create an Ollama profile in Admin Panel > LLM Profiles with:

• Provider: Ollama
• URL: http://localhost:11434
• Model: the model you pulled (e.g., qwen3:1.7b)

Alternatively, pass the Ollama URL and model as environment variables at startup — they serve as defaults if no LLM profile is configured:

ENABLE_LLM=true OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=qwen3:1.7b ./mockarty

Note: For production deployments, configure LLM providers through the Admin Panel UI. Environment variables OLLAMA_URL and OLLAMA_MODEL are convenience defaults and are overridden by the active LLM profile.

Configuring LLM Profiles

You can configure multiple LLM profiles via the Admin Panel:

1. Navigate to Admin Panel > LLM Profiles.
2. Click Create Profile.
3. Fill in:
   • Name — Display name for this profile.
   • Provider — OpenAI, Anthropic (Claude), OpenRouter, Google (Gemini), Mistral, Groq, Ollama (local), or Custom (any OpenAI-compatible endpoint).
   • URL — API endpoint URL.
   • API Key — Authentication key (if required by provider).
   • Model — Model identifier.
4. Click Save.
5. Set one profile as Default for all users.

Client-Side LLM

Users can also connect their own LLM provider directly from the browser, without routing API calls through the Mockarty server. This is useful when:

• Users have their own API keys for OpenAI, Claude, or other providers
• You want to avoid LLM traffic passing through the Mockarty server
• Different users need different LLM providers

When client-side mode is active, LLM API calls are made directly from the browser to the provider, while tool execution (mock creation, store updates, etc.) still happens server-side.

To use client-side LLM, users select a custom profile in the Agent Chat settings with their own API key and provider URL.

Per-Namespace Rate Limits

To prevent excessive LLM usage, configure rate limits per namespace:

1. Navigate to Admin Panel > LLM Profiles.
2. Under Rate Limits, set:
   • Requests per minute per namespace.
   • Requests per day per namespace.
3. Click Save.

Agent Chat

When the AI assistant is enabled, a floating chat button appears on every page of the Web UI. Users can:

• Ask questions about how to use Mockarty.
• Request mock creation using natural language descriptions.
• Get help with JsonPath expressions, Faker functions, and conditions.
• Troubleshoot mock matching issues.

Auto-Approve Mode

By default, the Agent Chat requires manual approval for each tool call (Accept/Decline buttons). You can enable auto-approve mode to automatically execute tool calls without confirmation:

1. Open the Agent Chat.
2. Find the Auto Approve dropdown at the top of the chat panel.
3. Switch from Manual to Auto Approve.

This setting is stored locally in the browser and persists across sessions. Use auto-approve when you trust the AI agent to execute operations without review — for example, during rapid mock prototyping in a sandbox namespace.

Caution: In production namespaces, consider keeping manual approval enabled to review each tool call before execution.

Security Best Practices

Follow these recommendations to keep your Mockarty installation secure.

Immediate Actions After Installation

1. Change the default admin password. The admin/admin credentials are publicly documented. Change the password before exposing the instance to any network.

2. Enable 2FA for admin accounts. Two-factor authentication adds a critical layer of protection for privileged accounts.

Network and Transport Security

3. Use HTTPS. Set up TLS certificates (auto-generated or custom) to encrypt all traffic. Set COOKIE_SECURE=true (this is the default) to ensure session cookies are only sent over HTTPS.

4. Keep SSRF protection enabled. The ALLOW_PROXY_TO_PRIVATE_IPS setting defaults to false, which prevents mock proxy mode from reaching internal network services. Do not change this unless you understand the risks.

5. Restrict network access. Use firewalls or network policies to limit who can reach the Mockarty ports:

   Port	Protocol	Purpose	Expose to
   5770	HTTP	Web UI, REST API, mock traffic	Users / teams
   5771	HTTPS	Encrypted Web UI, REST API, mock traffic	Users / teams (recommended)
   5772	HTTP/SSE	MCP server (only if ENABLE_MCP=true)	AI agents / trusted clients
   5773	gRPC	Coordinator (resolver/runner registration)	Internal: resolver and runner nodes only

Access Control

6. Use namespace isolation. Assign each team its own namespace with appropriate roles. This prevents accidental interference between teams.

7. Follow the principle of least privilege. Assign the lowest role that meets each user’s needs. Most users should have the User system role with the namespace User or Viewer role.

8. Rotate API tokens regularly. API tokens provide programmatic access. Rotate them periodically and revoke tokens that are no longer needed.

9. Review audit logs. Regularly check audit logs for unexpected activity, especially failed login attempts and admin actions.

Operational Security

10. Keep Mockarty updated. Apply updates promptly to receive security fixes.

11. Back up regularly. Configure automatic backups in Admin Panel > Backup. Periodically verify that backups can be restored.

12. Monitor system health. Use the health check endpoints (/health/live for liveness, /health/ready for readiness) to monitor the system’s status.

13. Enable contract testing. Use contract testing to detect mock drift and breaking changes. This ensures your mocks stay in sync with API specifications and prevents test environments from silently diverging from production behavior.

14. Test resilience with chaos engineering. Use chaos engineering to validate that your systems handle failures gracefully when Mockarty-dependent services experience faults (PRO license required).

Rate Limiting

Rate Limiting: API rate limits are configured through the database. Default limits: 10 requests/second, 60/minute, 1000/hour per scope (user/namespace/global), with burst of 20. Rate limit configuration can be managed via the admin API.

Environment Variable Summary

Security hardening (recommended production values):

HTTP / HTTPS listener:

Database:

Cache:

PDF report engine (Test Plan run export, optional):

The Test Plan run export endpoint can produce PDF files when an external rendering engine is available. Mockarty looks for the wkhtmltopdf binary on startup and uses it automatically — there is no env var to set in the common case. When the binary is not installed, the endpoint returns 501 Not Implemented with a JSON envelope explaining how to install it.

Build-tag note for chromium. The chromium engine is compiled in only when Mockarty is built with go build -tags chromium. The default release binary is distroless-friendly and ships only the wkhtmltopdf path. To enable Chromium-quality PDFs, rebuild Mockarty with that tag and make a Chromium binary available on PATH (or via MOCKARTY_PDF_CHROMIUM_BIN). For most operators the wkhtmltopdf engine is the simpler choice — install it via your distribution’s package manager and you are done.

Installing wkhtmltopdf:

The renderer is a single static binary published by wkhtmltopdf.org. Pick the command that matches your platform:

• Debian / Ubuntu — sudo apt-get update && sudo apt-get install -y wkhtmltopdf
• Alpine — apk add --no-cache wkhtmltopdf (also needs ttf-dejavu if you embed non-ASCII text)
• macOS — brew install --cask wkhtmltopdf (brew install wkhtmltopdf works on older Homebrew installs)
• CentOS / Rocky / RHEL — download the matching RPM from the official release page and install with rpm -i …. The distro-packaged version is often older than 0.12.6 and trips on flex CSS.
• Windows — download the .exe installer from the official release page, then point MOCKARTY_PDF_WKHTMLTOPDF_BIN at it.

After installing, restart Mockarty. The startup log will print test-plan PDF engine selected engine=wkhtmltopdf when detection succeeds. The PDF download button in the test-plan run report will work immediately — no env var required.

Troubleshooting: when the export still returns 501 after installing the binary, double-check it is on the admin-node user’s $PATH (which wkhtmltopdf) and that the binary is executable (wkhtmltopdf --version). If you installed it under a non-standard path, set MOCKARTY_PDF_WKHTMLTOPDF_BIN=/full/path/to/wkhtmltopdf and restart. Set MOCKARTY_DEBUG=1 to write the failing HTML payload to /tmp/mockarty-pdf-*.html for local re-rendering.

Cluster mode (multi-node deployments):

Multi-node rule. CLUSTER_MODE=true requires PostgreSQL (DB_USE=pg). SQLite does not support the advisory locks used for leader election.

Event bus (async event processing):

Analytics (opt-in, anonymous):

Test Plans (live logs and durable archive):

The Test Plans engine writes every item log line through a sink that fans out to two destinations: the primary store (the test_plan_item_logs table — used for replay in the UI) and an optional secondary archive (a local file or an S3 bucket — used for long-term retention or external SIEM ingestion). When secondary writes are unavailable the primary path keeps working — logs are never lost just because S3 is briefly down.

Air-gapped tip. Leave TESTPLAN_LOGSINK_SECONDARY empty in air-gapped installations. The primary database sink still keeps every log line and the live UI tail keeps working.

General:

Kubernetes Administration

When running Mockarty on Kubernetes, the admin node can manage the cluster lifecycle directly through the Admin API and CLI. The operator watches a MockartyCluster Custom Resource and reconciles resolvers, runners, and integrations automatically.

K8s Management Environment Variables

Admin API Endpoints

All Kubernetes endpoints require authentication and are scoped to the admin node.

Scale example:

curl -X POST http://localhost:5770/api/v1/k8s/scale \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"component": "resolver", "replicas": 5}'

Upgrade example:

curl -X POST http://localhost:5770/api/v1/k8s/upgrade \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"component": "runner", "version": "1.3.0"}'

RBAC

• Cluster operations (scale, upgrade, restart, status, logs) are restricted to users with the Admin or Support role.
• Namespace integrations (/api/v1/k8s/integrations) are available to Namespace Owners for their own namespaces, and to Admins for any namespace.

CLI Shortcuts

The CLI provides shorthand commands that call the Admin API under the hood:

# View cluster status
mockarty-cli cluster status

# Scale a component
mockarty-cli cluster scale resolver --replicas 5

# Upgrade cluster image tag (upgrades all components at once)
mockarty-cli cluster upgrade --tag 1.3.0

# Rolling restart
mockarty-cli cluster restart resolver

# Stream pod logs
mockarty-cli cluster logs <pod-name> --follow --tail 100

Audit Log Export & SIEM Integration

Mockarty keeps an immutable audit log of every authentication event, configuration change, and administrative action. The log can be exported from the Admin Panel or via the REST API in four formats, picked to match the ingestion pipelines of major SIEM platforms.

Authentication vocabulary. The following verbs are emitted automatically by the authentication subsystem and land in the exported stream without any extra configuration:

REST API

# CSV dump for the last 24 hours (milliseconds since epoch)
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/export?format=csv&from=$(date -u -d '1 day ago' +%s000)" \
     > audit.csv

# Syslog RFC 5424 — pipe directly into a SIEM collector
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/export?format=syslog" \
     | nc -u siem-collector.example.com 514

# ArcSight CEF for ingestion into an existing SIEM parser
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/export?format=cef" \
     > audit.cef

Supported filters: user_id, action, resource_type, resource_id, namespace, from, to, limit.

CLI

# Hourly syslog dump for SIEM ingest
mockarty-cli audit export \
    --format syslog \
    --from $(date -u -d '1 hour ago' +%s000) \
    --to   $(date -u +%s000) \
    > audit-$(date +%s).log

# CEF to file
mockarty-cli audit export --format cef --output audit.cef

# Filter by user
mockarty-cli audit export --format json --user-id u-42 --action login

Wire formats

• Syslog (RFC 5424) — one record per line, facility 13 (security/authorization). Structured-data block [audit@<PEN> key="value" ...] carries the full record. The default private-enterprise number is a placeholder; the value is set at build time for production deployments.
• CEF 0 — CEF:0|Mockarty|Mockarty|<version>|<action>|<name>|<severity>|<ext>. Extensions use the CEF dictionary (suser, src, act, rt, requestMethod, requestUrl, externalId, plus custom cs1/cs2/cs3 with labels for namespace/resource).

Both SIEM formats escape reserved characters (|, =, \, ", ], newlines) to guarantee one record per line and safe ingestion into any RFC- or CEF-compliant parser.

RBAC: audit export requires the admin or support role. The support role can export but not alter records.

Audit log retention

Audit log retention is driven by the scheduled audit_log_cleanup job in Admin Panel → Cleanup Policies. The default retention is configurable per deployment; beyond that value rows are hard-deleted to keep the table size bounded.

For regulated deployments (banks under 719-П ЦБ РФ §6.4, government systems under ФСТЭК приказ №17 п.4.2) Mockarty accepts a compliance floor expressed as an environment variable. When set, the cleaner silently raises any shorter retention configured via the UI up to the floor — an operator cannot accidentally shorten retention below a legally mandated minimum.

Typical values: 1095 for 719-П ЦБ РФ (3 years), 1825 for extended ФСТЭК policies (5 years). Leave unset for non-regulated deployments.

The floor is enforced on every cleanup tick and logged at WARN level whenever it raises the effective retention.

Audit legal holds

A legal hold is a retention-blocking freeze placed on the audit trail while a regulatory inquiry, incident investigation, or litigation is in progress. While at least one hold is active, the retention cleanup job preserves every audit row whose timestamp falls inside the hold’s window — even if the normal retention has already expired.

Legal holds satisfy three concurrent requirements:

• SOX §802 / 18 USC §1519 — destroying records under an active preservation notice is a criminal offence in the United States.
• 719-П ЦБ РФ §6.4 — bank operators must be able to freeze audit trails on demand for ЦБ inspections.
• ФСТЭК приказ №17 п.4.2 — audit integrity during security-incident investigations.

Each hold is a range — from a start timestamp to an optional end timestamp (open-ended holds are allowed) — and can be scoped to a single namespace or applied globally. Placing or releasing a hold is itself audited via the audit_legal_hold_applied and audit_legal_hold_released verbs.

REST API

# Place a hold covering the last 7 days for namespace "prod"
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "reason": "INC-42 preservation",
       "from_time": "2026-04-12T00:00:00Z",
       "to_time":   "2026-04-19T23:59:59Z",
       "namespace": "prod",
       "filter_summary": {"ticket": "INC-42"}
     }' \
     "$MOCKARTY_URL/api/v1/admin/audit/legal-holds"

# List all holds (status: active|released, limit 1..1000)
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/legal-holds?status=active"

# Release a hold (idempotent — repeat calls return 200 with the released row)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/legal-holds/<hold-id>"

Behaviour

• While any hold is active, the retention cleaner skips rows covered by it. The baseline DELETE plan is unchanged when no hold exists, so unregulated deployments pay zero overhead.
• Namespace-scoped holds protect only rows inside that namespace. A hold with namespace omitted covers every namespace.
• An open-ended hold (to_time omitted) covers every row from from_time onward, with no upper bound.
• Released holds are never deleted — they remain in the audit_log_legal_holds table as an evidentiary trail of what was held, when, and by whom.
• RBAC: admin only for POST / DELETE. support can list holds (read-only SOC visibility) but cannot place or release them.

Safety

If the database is unreachable at cleanup time, the cleaner aborts the current tick rather than risk deleting held rows. The scheduler retries on its next interval.

Compliance build: pure-Go SQLite

Mockarty ships with two SQLite drivers selected at build time via Go build tags:

All production Dockerfiles (Dockerfile.mockarty, Dockerfile.runner, Dockerfile.resolver, Dockerfile.operator, Dockerfile.server-generator, Dockerfile.mockarty-license-server) build with CGO_ENABLED=0. Auditors can confirm the linked driver on a release binary with:

go tool nm mockarty | grep -E 'sqlite3?' | head

A compliant build contains only modernc.org/sqlite symbols and no github.com/mattn/go-sqlite3 references.

Field-level PII encryption at-rest

For regulated deployments under 152-ФЗ УЗ-3 / УЗ-4 (personal-data protection law of the Russian Federation) and 719-П ЦБ РФ §6.5 (bank customer-data protection), Mockarty can encrypt high-volume personal-data columns at the application layer. Covered columns: audit log user_agent (stable PII fingerprint written on every authenticated request), user email, and user full_name (ФИО).

The feature is off by default — leaving the env variables unset keeps the columns in plaintext, which is the correct behaviour for dev and non-regulated deploys. Enabling it is a zero-downtime operation: existing plaintext rows continue to read correctly through a transparent passthrough, and new rows are written as encrypted envelopes.

Generating the secrets (on any trusted workstation; keep both values in your secrets manager as independent entries):

# AES-256 encryption key (exactly 32 bytes)
openssl rand -base64 32
# HMAC pepper for blind index (32 bytes minimum — longer is fine)
openssl rand -base64 32

Why two separate secrets. The encryption key protects confidentiality of the stored envelopes; the pepper keyes deterministic hashes used for equality lookups (login by email, OAuth / SAML account matching) and substring search. A compromise of one must never automatically compromise the other, so both are stored as distinct entries in your secrets manager and rotated independently.

What is encrypted. Applying both env vars encrypts: audit user_agent, user email and user full_name. All lookups required by the system (login by email, OAuth/SAML account matching, admin search) continue to work transparently — Mockarty maintains deterministic search indexes so functionality is fully preserved. An attacker who obtains a copy of the database cannot derive the underlying email or name without the pepper.

Rotation:

• Never swap the key on a running cluster while encrypted rows still exist with the old key. Rotate by deploying the new key alongside the old one, running the backfill to re-encrypt all rows, then removing the old key after the backfill completes.

Backfilling legacy plaintext rows

After you turn encryption on for the first time, rows written before that point remain in plaintext. The read path handles them transparently, so there is no outage; to convert them to encrypted envelopes, run the backfill subcommand during a maintenance window:

# audit_logs.user_agent — count candidate rows (no writes)
./mockarty --pii-backfill audit_logs --pii-backfill-dry-run

# audit_logs.user_agent — re-encrypt in 1000-row batches
./mockarty --pii-backfill audit_logs --pii-backfill-batch 1000

# users.email + users.full_name + hmac + trigrams (requires MOCKARTY_PII_HMAC_PEPPER)
./mockarty --pii-backfill users --pii-backfill-dry-run
./mockarty --pii-backfill users --pii-backfill-batch 500

# Cap total work for a rehearsal on a large table (10 batches × 500 rows)
./mockarty --pii-backfill audit_logs --pii-backfill-max-batches 10

The users target encrypts email and full_name together with their associated search indexes. A malformed row aborts only that row — the rest of the batch is unaffected.

Properties:

• Idempotent. Already-encrypted rows are skipped, so re-running after a crash or pod restart is safe.
• Non-blocking. Batches are committed independently — reads and writes continue at normal throughput throughout the backfill.
• Signal-safe. SIGINT/SIGTERM stops after the current batch; the next run picks up where the previous one left off.
• Requires both keys. The subcommand fails immediately if MOCKARTY_PII_ENCRYPTION_KEY is missing or malformed. The users target additionally requires MOCKARTY_PII_HMAC_PEPPER.

Run against the main database (same DB_DSN, DB_USE as the admin node). The command exits 0 on success and prints a summary line: PII backfill complete: table=audit_logs column=user_agent scanned=... encrypted=... skipped=... batches=... dry_run=false.

KeyStore Backend: software or HSM (PKCS#11)

For gov-sector deployments (ФСТЭК приказ №17 п.21, УЗ-2 and above) and bank-sector deployments (ЦБ РФ 719-П §5.1), storing long-lived AES / HMAC keys as environment variables is insufficient — the regulator requires the key material to live on certified hardware (FIPS 140-2 Level 2+ or ФСТЭК КС2/КС3). Mockarty abstracts key sourcing behind a single KeyStore interface with two interchangeable backends.

How it works. The key-encryption key (KEK) never leaves the HSM. At startup, Mockarty authenticates to the PKCS#11 token and uses the KEK to unwrap the data-encryption key — the unwrapped material is kept only in process memory and zeroed on graceful shutdown. Revoking HSM access (rotate the PIN, revoke the user, power-cycle the token) is sufficient to lock every running and future Mockarty instance out of the encrypted data.

Building with PKCS#11 support. The default Mockarty binary is CGO-free (distroless-compatible) and does not link any PKCS#11 library. Operators who need HSM integration build their own image with the pkcs11 build tag:

# CGO is required; add the HSM vendor's PKCS#11 shared library to the library path.
# Contact your Mockarty vendor or refer to your CI/CD pipeline documentation for
# environment-specific build instructions with -tags pkcs11.
CGO_ENABLED=1 go build -tags pkcs11 -o mockarty

Selecting MOCKARTY_KEYSTORE=pkcs11 on a binary that was not compiled with the tag fails fast at startup with keystore: PKCS#11 backend is not compiled in — rebuild with -tags pkcs11, so a misconfigured deployment never silently downgrades to software keys.

Key provisioning (example with SoftHSMv2 for staging — replace with your certified HSM in production):

# 1. Create a token and set a user PIN (done once per HSM / slot).
softhsm2-util --init-token --slot 0 --label mockarty --pin 1234 --so-pin 5678

# 2. Generate the KEK on the HSM. The key never leaves the token.
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --slot 0 --login --pin 1234 \
    --keygen --key-type AES:32 --label mockarty-pii-kek --usage-wrap --usage-decrypt

# 3. Generate a fresh DEK out-of-band, wrap it under the KEK, export base64:
openssl rand 32 > /tmp/dek.bin
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --slot 0 --login --pin 1234 \
    --encrypt --mechanism AES-CBC-PAD --iv $(printf '%.0s00' {1..16}) \
    --input-file /tmp/dek.bin --output-file /tmp/dek-wrapped.bin --label mockarty-pii-kek
base64 -w0 /tmp/dek-wrapped.bin    # → value for MOCKARTY_PKCS11_WRAPPED_PII_KEY

# 4. Same flow for the HMAC pepper (32 random bytes wrapped under the same KEK).
# 5. Delete the plaintext DEK and pepper from the operator's workstation.
shred -u /tmp/dek.bin

Health reporting. The /health endpoint includes a keystore section with the active backend kind (software or pkcs11), the pkcs11_compiled_in flag, and the result of the PKCS#11 session probe (C_GetSessionInfo). A dropped HSM session surfaces as an unhealthy pod; the operator rotates the deployment to re-authenticate.

Compliance mapping. ФСТЭК приказ №17 п.21 (УЗ-2+ hardware key protection), ЦБ РФ 719-П §5.1 (payment-infrastructure HSM requirement), 152-ФЗ УЗ-3 (separation of key custodian from data custodian — the HSM is the custodian of the KEK, Mockarty is the custodian of the data).

See Also

• Quick Start Guide — Get up and running in 20 minutes
• Installation & Deployment — Docker deployment, environment variables, and TLS configuration
• Integrations Guide — Set up resolver nodes, runner agents, and webhooks
• Contract Testing — Validate mocks against OpenAPI specs and detect mock drift
• Chaos Engineering — Fault injection experiments for resilience testing (PRO)
• UI User Guide — Comprehensive guide to the Web UI
• API Reference — Full REST API documentation for programmatic access