Config Tamper Detection

Monitors critical files for unauthorized changes, deletions, or unexpected additions.

note

This guard is primarily relevant to administrators and self-hosted deployments where configuration files are accessible on disk. In hosted deployments, configuration is managed through the dashboard and this guard works automatically.

What It Does

Some files are too important to change without authorization — your agent's core configuration and personality files, for example. Config Tamper Detection takes a snapshot of these files when your system starts, then periodically checks to see if anything has changed. If a file is modified, deleted, or a new unexpected file appears, it raises an alert.

Think of it as a tripwire system — invisible until someone disturbs something they shouldn't. The guard quietly watches over your most sensitive files and sounds the alarm the moment something is out of place.

Why It Matters

An attacker who can modify your agent's configuration can change its behavior without being detected. They could alter how the agent responds, what data it has access to, or how it interacts with users — all without leaving an obvious trace. This guard ensures you know immediately if critical files are tampered with, giving you the chance to respond before any damage is done.

What Gets Caught

• Modified files — any monitored file whose content has changed since CrabShield started
• Deleted files — monitored files that have been removed
• Unexpected new files — files that appear in monitored locations that weren't there at startup

What won't trigger it: Legitimate configuration changes made through the CrabShack dashboard, which go through the proper signed update process.

Example

Scenario

An agent's personality file (SOUL.md) is edited directly on disk instead of through the CrabShack dashboard. Config Tamper Detection's periodic check notices the file's content has changed since the last verified snapshot. A critical alert is raised, and the audit log records a file_modified event with the file path, the time of the last known good state, and the time the change was detected. If the change was made through the dashboard, it would have been signed and would not have triggered the guard.

Settings

Setting	What It Controls
Check Interval	How often to verify file integrity
Monitored Files	Which files to watch for changes
Audit Logging	Whether to log tampering events to the audit system

How It Responds

File modifications trigger a critical alert. Deletions and unexpected new files trigger standard alerts. All events are logged with details about what changed and when.

If This Guard Blocks You

1. Check the audit log. Navigate to Security > Audit Log in the CrabShack dashboard. Filter by Config Tamper Detection to find the relevant event. Click on the event row to expand it and see details including which skill and channel triggered it, the session key, and additional context.

2. Understand the detection. The audit log shows what happened — file_modified (a monitored file's content changed), file_deleted (a monitored file was removed), or unexpected_file (a new file appeared in a monitored location). If you made the change intentionally but outside the dashboard, revert the change and make it through the dashboard instead, where it will be properly signed. If you didn't make the change, investigate immediately — this could indicate unauthorized access. The guard monitors core configuration and personality files automatically.

3. Adjust if needed. This guard doesn't have modes or exemptions — configuration changes should always go through the dashboard. If the guard is alerting on files you manage outside CrabShack, ensure those files aren't in a monitored location. See the Configuration page for details.

tip

Prefer creating a targeted exemption for a specific skill or channel over disabling the guard entirely. If you're seeing frequent false positives, a suppression lets you silence a specific detection label temporarily while you refine your settings.

Default Behavior

Enabled with periodic checks. Core configuration files are monitored automatically.

Related Guards

• Skill Verification — uses cryptographic signatures to verify skill code integrity, complementing Config Tamper Detection's focus on configuration files.
• Filesystem Fence — prevents agents from accessing or modifying protected files, adding real-time access control to Config Tamper Detection's periodic integrity checks.
• Audit & Alerts — receives all tampering events and can deliver real-time alerts when changes are detected.