Administrator

Administrator Guide

This guide covers Maskink's masking engine, rules, lists, the configuration of the AI chat and the administration settings. Here you can find what each section of the Settings screen does, how to find out why a value was or was not masked, and how to add rules specific to your organization.

User guide →

01Login and access

• Settings are reached through the gear icon at the top right.
• First use: If there is no administrator password yet, the Settings screen asks you to set one (at least 8 characters). There is no separate installation step; the database and the default rules are created automatically on the first request.
• Lockout: After 5 failed logins in a row, that IP address is locked for 5 minutes.
• Session: The session ends after a period of inactivity (set in the Security section). You can also end it with Sign out at the top right.
• Masking screen: By default anyone on the network can mask; settings are always password-protected. You can require login for masking as well.

02How does the engine work?

For every masking request the engine applies these steps in order:

1. Mode detection. If the user chose Automatic, the content is classified as log or script from its line structure. Some rules only run in one mode.
2. Candidate collection. All enabled rules that match the mode run on the text; every match (or capture group of the rule) becomes a candidate.
3. Filtering and validation. Each candidate goes through the keep lists, the variable-reference check, length limits, the exclude regex and the validators (Luhn, TCKN, IBAN, entropy…). Rejected candidates are recorded with a rejection reason.
4. Reclassification. In rules that allow it, the category is corrected based on the value itself: a value that looks like an IP becomes IP, CORP\john is split into DOMAIN + USER, PC01$ becomes HOST and a dotted name becomes FQDN.
5. Overlap resolution. Among overlapping candidates the one with the higher priority wins; if equal, the longer one; if still equal, the one that starts first.
6. Propagation. Found values (if propagation is on for their category and they meet the minimum length) are also masked where they appear elsewhere in the text without context. The first label of an FQDN (db01.corp.local → db01) propagates as HOST. Parts inside a path (after / or \) are not masked by propagation.
7. Token generation. Each unique value is turned into a token with its category's placeholder template. Numbers that would clash with a token already present in the text are skipped.
8. Chat mapping (Chat screen only). The browser sends the chat's mapping table so far with the request. Values masked in earlier messages are found even without context in this message and get the same token; new values get the next unused number. The first labels of earlier FQDNs are also searched for as HOST. These matches appear in the mapping table with the rule Chat mapping (earlier message).
9. Warnings. If a risk keyword appears on a line where nothing was masked, the user is warned.

03Overview

The opening screen of Settings:

• Usage cards: Total runs, characters processed, values masked and average time (if statistics are enabled).
• Last 14 days: A chart of daily runs.
• Rules: Total, enabled, custom and broken rule counts; Maskink, PHP and PCRE versions and the JIT status.
• Rules per category: How many rules are enabled in each category. Clicking a category filters the Rules screen by it.

If a regex fails to compile, it is listed here in a red box and a counter appears next to Rules in the side menu.

04Rules

Each rule defines how one kind of data is recognized. On the list screen:

• Search and filters: Search in name, description, pattern or keys; filter by category, type and state (Enabled, Disabled, Custom, Built-in, Broken).
• Enabled switch: Turns the rule on or off immediately.
• Bulk actions: Select with the checkboxes and choose Enable / Disable selected.
• Edit: Opens the rule editor.
• Duplicate: Creates a disabled copy of the rule. Ideal for experimenting without changing a built-in rule.
• Delete: Only custom rules can be deleted. Built-in rules cannot be deleted; they can be disabled or reset to default.

Names and descriptions of built-in rules are shown in the interface language; the edit form shows the stored (English) values.

Rule types

05Rule editor

The editor has two parts: the rule fields on the left and the Live test on the right. Every change is tried on the sample text at the right immediately, before saving.

Common fields

• Name / Description: Shown in the list and in the "Detected by rule" column of the mapping table.
• Main category: Which token the match is masked with.
• Priority (0-1000): The higher one wins on overlaps. Guide values: passwords/keys ~90, contextual rules ~70-80, generic patterns (IP, FQDN, first.last) ~40-60.
• Runs in mode: All, Log only or Script only.
• Enabled: Whether the rule runs.

Regex rules

• Pattern: PCRE syntax, written without delimiters (/…/). Unicode (u) is always on.
• Templates: {{TLD}} expands to the TLD list, {{FIRSTNAME}} to the first-name dictionary (lowercase) and {{FIRSTNAME_CAP}} to capitalized names. When you update a list, all rules using that template are updated too.
• Flags: i case-insensitive, m multiline, s dot also matches line breaks, x extended (whitespace and comments allowed), U ungreedy.
• Capture group → category: If empty, the whole match is masked with the main category. If you define groups, only those groups are masked and each group can get its own category. For example, for https://user:password@server: group 1 → USER, group 2 → PASSWORD.

Key = value rules

• Keys: One key per line. Space, _, - and . match loosely; writing user name catches username, user_name, User-Name, UserName and "user name". Case-insensitive.
• Supported forms: key=value, key: value, "key": "value" (JSON), $Key = 'value' (PowerShell), key => value (PHP), ['key'] = value.
• Prefix / suffix: None catches only the exact key; Prefix also catches prefixed keys such as db_user and smtp.user; Prefix + suffix also catches keys with additions on both sides such as db_password_enc.
• Separator: Standard (= : => := ==), only =, or standard + space (for CLI forms such as password S3cret).
• Value regex: If empty, a quoted value or an unquoted value up to the next separator is taken. Fill it in to enforce a specific format.
• Also scan XML tags: Also catches the <password>…</password> form.

Dictionary rules

Write one term per line. A term can get its own category with the term | CATEGORY form; lines starting with # are comments. Terms are matched as whole words; if Case-sensitive is off, differences in case are ignored.

Filtering and validation

Live test

Type or paste sample text into the area on the right; try log/script behavior with the mode selector. The test results:

• Highlighted sample: Found values in their category color; hover to see the rule and category.
• Masked: The result with all enabled rules plus the unsaved version of the rule you are editing.
• Rejected candidates: Every dropped value and the reason. Common reasons: Variable / placeholder reference, Numbers only, Short numeric value, Code reference (object.property), Script variable, Subnet mask / wildcard, Luhn / TCKN / IBAN check failed, Looks like a domain name.
• Compiled regex: The actual pattern produced by key=value and dictionary rules. Useful when debugging.

The test text is remembered per rule in your browser; it is not saved on the server. If you try to save a broken regex, the editor shows the error and does not save. For built-in rules, Reset to default reverts your changes.

06Example: a rule for organization server names

If your servers are named like ACME-WEB01 and ACME-DB02:

1. Rules → + New rule.
2. Name: Organization server names, Main category: Hostname (HOST), Type: Regex, Priority: 75, Mode: All.
3. Pattern: \bACME-[A-Z]{2,5}\d{2,3}\b, flag: i.
4. Type ACME-WEB01 restarted; acme-web01 reachable into the live test area and check that both spellings get the same <HOST_1> token.
5. Save.

07Custom dictionary

For terms specific to your organization that cannot be recognized by a pattern: server names, project code names, customer and partner names, internal system names. Line format:

# Servers
ACME-DC01 | HOST
SECRET-SRV | HOST
# Projects and customers
Project Falcon
AcmeBank | CUSTOM
special.person | USER

If no category is given, the rule's main category (Custom term) is used. Advanced editor opens the dictionary rule in the full editor, giving access to the live test and the case setting. You can create several dictionary rules for separate topics (Rules → New rule → Type: Dictionary).

08Categories and tokens

These fields are set for each category:

• Label: The name shown in the interface. Labels of built-in categories are stored in English and translated on display.
• Token prefix: Replaces {CAT} in the template (e.g. PASS for PASSWORD).
• Color: The highlight color in the output.
• Placeholder template: If empty, the general template is used.
• Propagation: Are values of this category searched for everywhere in the text?
• Case-sensitive: If on, John and john get separate tokens. On for categories where case matters, such as passwords and keys.
• Enabled / Order: Disabled categories are never masked and do not appear on the user screen; the order sets the layout of chips and lists.

Template variables

09Lists and exceptions

These control how the engine recognizes and excludes values. Changes apply to all rules as soon as they are saved. reset to default next to each list restores it. Items are separated by lines or commas; lines starting with # are comments.

10General settings

• General placeholder template: The default token format for all categories (default <{CAT}_{n}>). Click the ready-made options to preview them.
• Propagation: The global switch. The per-category setting applies in addition.
• Minimum length for propagation: Prevents short values such as it and db from being masked everywhere in the text.
• Default mode: The mode selected when the user screen first opens.
• Keep subnet masks: Values such as 255.255.255.0 and 0.0.0.255 are not treated as IPs; they stay visible for network analysis.
• Remaining-risk keywords: If this regex matches on a line where nothing was masked, the user is warned. If left empty, no warning is given.
• Maximum input (KB): Size of text that can be masked at once. Very large values may hit PHP memory and time limits.
• Keep usage statistics: Records only numeric statistics (characters, match count, duration); content is never stored. Each chat message also counts as a masking run.

Chat-related settings are in the Chat (AI) box at the bottom of the same screen; see the next section.

11Chat (AI)

The Chat screen places Maskink between the user and the AI service. The browser never talks to the AI service directly; all requests go through api.php on the server.

1. The browser sends the new message as is, the earlier messages masked and the chat's mapping table to the server (session + CSRF protected).
2. The server runs the new message through the engine (with the chat mapping). The request to the model is: system prompt + masked history + masked new message. Real values never reach the AI service.
3. The model's reply arrives as a stream (SSE) and is passed to the browser masked.
4. Restoring happens in the browser with the chat's mapping table. Besides the exact token form, small distortions models often make (dropped angle brackets, HTML escaping such as <IP_1>) are recognized. Tokens not in the mapping are shown to the user as a warning.

Settings → General settings → Chat

• Default model: The model selected in new chats. The list is read live from the connections; users can pick another model on the chat screen.
• Temperature: Between 0 and 2; if left empty the model's own default is used. Low values (0–0.3) are more consistent for technical support and command generation.
• System prompt: Added at the start of every request. {EXAMPLE} is filled with sample tokens built from the current token template (e.g. <IP_1>, <HOST_1>) and {CATEGORIES} with the list of enabled categories. The default prompt is in English and tells the model to reply in the user's language. Reset to default restores it.

Screenshots

Users can add screenshots to the chat. Sensitive parts of the image are covered in the browser; the server does not read, change or store the image.

1. The text in the image is read with OCR in the browser (Tesseract.js, Turkish + English; the files are in assets/vendor/tesseract/, no internet needed). The image is not sent anywhere for reading. It is preprocessed first (2–3x upscaling if small, grayscale, contrast stretching, inversion if mostly dark) and read in two passes: page layout (PSM 3) and sparse text (PSM 11). The second pass only adds words the first missed or read poorly.
2. Table columns: Cells in columns with headers such as User, Username, Account, Owner, Server, Host, Computer, Display Name (and their Turkish equivalents) are masked in the matching category even without rule context. A line crossing the column boundary (a plain sentence) or a large vertical gap marks the end of the table.
3. The text that was read is masked through the mask endpoint using the chat's mapping; the word boxes of every masked value are fully covered and its token is written on top.
4. Manual correction: The user can select a word and give it a category (hints: the value is masked in that category everywhere) or right-click a covered area to unmask it (allow: the value stays visible everywhere). Both are engine options and are also sent to the server; they apply equally to the message text and the text read from the image. Words that could not be read reliably, or that look like identifiers but were not masked, get an orange frame.
5. Right before sending, the text read from the image is masked again with the current mapping, including the new values of the message, and the image is rendered in its final form (longest side 2000 px, JPEG). This way a value masked in the message is also covered in the image.
6. The original image is also stored in the user's browser (only there; it is compared using the What the AI sees switch in the chat). The image that reaches the server is always the covered one.
7. The server masks the text read from the image once more with the same mapping, hints and allow, and sends the model message + masked image text + covered image. If the model does not support images, only the text is sent. At most 6 images from the history are sent to the model again.

Which models accept images is set on the AI connections screen (Ollama reports this itself).

Where the models come from is managed on the AI connections screen, described in the next section.

Storage and privacy

• Chats and mapping tables live only in the user's browser (localStorage); there is no copy on the server or in the database. Administrators cannot see users' chats.
• Messages are held in memory on the server only for the duration of the request. Only numeric usage statistics (if enabled) are written to the database.
• The AI service sees only masked text. Whether it logs requests on its side is outside the control of this application.
• If Require login for the masking screen too is on, the chat can also be used only with an administrator session.

12AI connections

The Settings → AI connections screen lists the endpoints used by the chat. Each connection consists of an address, an optional API key and a model list. Models of enabled connections appear in the chat's model list, grouped under the connection name.

• + New connection: Opens an empty form.
• Edit: Opens the connection's form; changes are applied with Save.
• Test connection: Fetches the model list with the (not yet saved) details in the form and shows the models found. With a manual model list, a very short test request is sent to the first model.
• ↑ / ↓: Changes the order of the connection; saved immediately. Groups in the chat's model list follow this order.
• Delete: Removes the connection. Chats using its models will have to choose another model on the next message; if the default model is on this connection, choose a new one under General settings.

Form fields

Connection types

Default connections

The connections used until you save your own are defined in src/Seeds.php → llmConnections(). Adjust them to your environment on this screen; your changes are stored in the database.

13Backup / restore

• Export: Downloads all rules, categories and editable settings as JSON. The administrator password and the installation-specific secret key are not exported.
• Import: Built-in rules are matched by their key (bkey) and updated; custom rules are matched by name + type + category and added if missing. Importing the same file twice does not duplicate rules. With Delete existing custom rules first, your custom rules are replaced by those in the file. Exports from the earlier Turkish-only version (maskara) are accepted too.
• Add missing defaults: Adds built-in rules introduced in a new version; existing rules are left untouched.
• Reset built-ins: Resets all built-in rules and categories to their original state. Your custom rules are kept; changes made to built-in rules are lost.

14Security and change log

• Change the administrator password: Asks for the current password and a new one of at least 8 characters.
• Require login for the masking screen too: When on, masking is possible only with an administrator session.
• Session timeout: In minutes, at least 5.
• Change log: Rule, category and settings changes and successful/failed login attempts are recorded with time and IP address (the last 500 entries are shown).

All administrative requests are protected by the session and a CSRF token. Masked texts are not stored on the server; the mapping table stays only in the user's browser page.

15Troubleshooting

A value is not masked

1. Paste the line into the Live test area of a suitable rule (e.g. kv_password for a password).
2. If the value appears under Rejected candidates, fix it according to the reason: remove it from the keep list, relax the validator or length limit, review the "Skip variable references" option.
3. If there is no candidate at all, no rule catches the value: add a new key to a key=value rule, write a new regex rule or add the term to the custom dictionary.
4. If an FQDN is not recognized, its extension is most likely missing from the TLD list.
5. If the rule runs in only one mode, try changing the test mode.

Unneeded things are masked

• If a value should stay visible everywhere, add it to Values that are never masked; for a domain use Domains that are not masked, for an IP range IPv4 ranges that are not masked.
• If a specific rule produces false positives (find it in the "Detected by rule" column of the mapping table), add an exclude regex, lower its priority or disable it.
• If code expressions such as logger.info are taken for first.last, add them to Code tokens; if file names are taken for users, add them to Parts excluded from first.last.

"broken" label in the rules list

The rule's regex cannot be compiled; the engine skips this rule and the others keep working. Hover over the label to see the error message. Usually a change made to a list (e.g. a special character added to the TLD list) breaks rules that use a template.

Chat: the model list cannot be loaded

• Open the connection on the AI connections screen and press Test connection; the error message shows the problem. The chat screen also reports unreachable connections with a yellow warning.
• Check access from the server to the endpoint: the model list address (e.g. {address}/v1/models) must open from the server itself (proxy, firewall).
• If the error is about TLS/certificates, check PHP's curl.cainfo setting; as a last resort, turn off Verify the TLS certificate for the connection.
• If a model says “HTTP 302/401” or “authorization required”, it needs an API key: enter the key on the relevant connection and exclude the model from the connection without a key.

Chat: the reply arrives all at once instead of streaming

A compression or buffering layer in between (e.g. Apache mod_deflate, a reverse proxy) is holding the stream. Turn off compression and buffering for text/event-stream responses; the application already sends the X-Accel-Buffering: no header.

Chat: unrestored tokens in the reply

The model has distorted or invented a token. Check that the token instructions in the system prompt are in place; if the problem keeps happening with a particular model, choose another model as the default. Keeping the token template short and distinctive, such as <{CAT}_{n}>, makes it easier for models to preserve tokens.

Chat: a screenshot is not read

• If the window stays in the “Preparing OCR” state, check that the browser can fetch the files under assets/vendor/tesseract/ (e.g. the …/lang/tur.traineddata address should open). The files are about 13 MB; they are cached in the browser after first use.
• If text is read incompletely, the image may be too small or blurry; zoom in and take a new screenshot. The user must cover unreadable areas by hand.
• If a model gives a “not a multimodal model” error, remove it from the connection's Vision-capable models list.

Masking is slow or times out

Check on the Overview that PCRE JIT is on, lower Maximum input and simplify custom regexes with broad, nested repetition such as .*.

16Technical notes

• There is no installation. When the folder is copied to the web server, the database, tables and default rules are created automatically on the first request.
• Database connection: config.php (host, port, database name, user, password). This file is not accessible over the web.
• Tables: mk_settings (settings), mk_categories, mk_rules, mk_audit (change log), mk_usage (numeric statistics).
• Built-in rules are defined in src/Seeds.php; the engine is in src/Engine.php. After upgrading, run Backup → Add missing defaults.
• The interface uses no CDN; Tailwind is loaded from the local assets/js/tailwind.js file, so no internet connection is needed.
• Access: the src/, partials/, guides/ and lang/ folders are not accessible over the web.
• Chat components: page chat.php, client assets/js/chat.js, screenshot reading and covering assets/js/vision.js (Tesseract.js 5.1.1, assets/vendor/tesseract/), connection client src/Llm.php (default connections in src/Seeds.php → llmConnections()); endpoints api.php?action=chat.models, chat.send and, for administration, llm.list, llm.save, llm.test, llm.reorder, llm.delete. The application root opens the Chat screen directly.
• Language: The interface is English by default; the language button in the top bar switches to Turkish (the choice is kept in the mki_lang cookie). Translations live in lang/tr/*.php, each returning an [English => Turkish] array; PHP uses t() / te() and JavaScript uses MK.t(). Names of built-in rules and categories are stored in English and translated on display.
• Database and session: Maskink uses its own maskink database, the MASKINKSESS session cookie and mki- prefixed browser storage, so it is independent of other installations on the same server.