Troubleshooting

How to identify and resolve issues caused by CrabShield security guards.

Is CrabShield Blocking Something?

If something isn't working as expected, CrabShield may be involved. Here are common symptoms:

• You see a generic security error — a guard blocked a message or action, and only a generic response was returned
• Messages contain [REDACTED_BY_CRABSHIELD] — the Credential Vault detected sensitive information and replaced it
• A tool call fails unexpectedly — Tool Gate or another guard blocked the agent from using a tool
• The agent stops responding after a config change — CrabShield may have entered lockdown mode due to a configuration integrity issue
• A skill or integration stopped working — a guard may be blocking a connection, tool, or file access that the skill relies on

How to Investigate

Follow these three steps whenever you suspect CrabShield is involved:

Step 1: Check the Audit Log

Open the CrabShack dashboard and navigate to Security > Audit Log. This is the single source of truth for everything CrabShield does. Every detection, block, and warning is recorded here.

• Filter by time to narrow down when the issue started
• Filter by guard name if you suspect a specific guard
• Look at the detection label — this tells you exactly what was flagged
• Look at the action taken — Block, Sanitize, Warn, or Log
• Click on an event row to expand it and see details like the skill name, channel ID, and session key — these are the values you'll need if you want to create an exemption

Step 2: Identify the Guard and Context

Once you find the relevant audit log entry, click on it to expand the details. Note which guard generated it and the context fields — the skill name and channel ID are shown here when available. Each guard has its own documentation page with details about what it catches and why. Visit the guard's page to understand the detection.

Step 3: Decide on an Action

Situation	Recommended Action
False positive on a specific message	Create a suppression for that detection label (temporary)
A trusted skill needs to bypass a guard	Create an exemption for that skill (find the skill name in the event details)
You're not sure if detections are accurate	Switch the guard to Warn mode to monitor without blocking
A guard is too aggressive for your use case	Adjust the guard's settings or custom patterns
Everything looks correct	The guard is working as intended — no action needed

See the Configuration page for details on exemptions, suppressions, and guard modes.

Common Scenarios

Agent stopped responding after a config change

Likely cause: CrabShield detected a configuration integrity issue and activated lockdown mode. In lockdown, several guards switch to stricter settings to protect your agents.

What to do:

1. Check the audit log for a Config Tamper Detection event around the time of your change
2. If you made the change through the CrabShack dashboard, it should have been signed automatically — contact support if lockdown persists
3. If you made the change outside the dashboard, the change won't have a valid signature. Revert the change and make it through the dashboard instead

Users getting messages blocked unexpectedly

Likely cause: The Prompt Injection guard is detecting patterns in user messages that resemble manipulation attempts (false positives).

What to do:

1. Check the audit log and note the detection label (e.g., role_play_attempt, instruction_override)
2. If the detection is a false positive, create a suppression for that detection label
3. Consider switching the guard to Sanitize mode instead of Block — this neutralizes potential threats while still allowing the conversation to continue
4. If a specific phrase keeps triggering detections, you may need to adjust custom patterns

Skill suddenly can't use a tool

Likely cause: Tool Gate is blocking the tool. This could be because the tool is on the default denylist, a rate limit was exceeded, or the guard detected a suspicious sequence of tool calls.

What to do:

1. Check the audit log for a Tool Gate event — it will show which tool was blocked and why
2. If the tool is on the denylist and the skill legitimately needs it, create an exemption for that specific skill
3. If a rate limit was exceeded, consider raising the limit in the exemption or adjusting the global rate limit
4. If a suspicious sequence was flagged, review whether the skill's behavior is expected

MCP integration stopped working

Likely cause: MCP Hardening is blocking the connection. MCP Hardening blocks all external tool servers by default — only servers on your allowlist are permitted.

What to do:

1. Check the audit log for an MCP Hardening event — it will show which server was blocked
2. Add the server to the MCP Hardening allowlist in the dashboard
3. Make sure the transport method (local or network) is also allowed
4. If the server was previously working, check whether the allowlist was modified or the server's address changed

[REDACTED_BY_CRABSHIELD] appearing in messages

Likely cause: The Credential Vault detected something that looks like a credential, API key, or personal information and replaced it with a placeholder.

What to do:

1. Check the audit log for a Credential Vault event to see what was detected
2. If the detection is correct, the guard is working as intended — avoid sharing credentials in conversations
3. If it's a false positive (e.g., a string that looks like an API key but isn't), create a suppression for that detection label
4. If a specific channel handles data that routinely triggers this guard, consider creating an exemption for that channel

A guard keeps firing but you're not sure why

Likely cause: The guard's detection patterns are matching something in your normal workflow.

What to do:

1. Switch the guard to Warn mode temporarily — this lets everything through while still logging detections
2. Review the audit log over a day or two to understand what's being flagged
3. Decide whether to create exemptions, suppressions, or adjust settings based on what you see
4. Switch back to your preferred mode once you've made adjustments

General Tips

• Use Warn mode as a diagnostic tool. Whenever you're unsure about a guard's behavior, switch to Warn mode to see what it catches without disrupting your agents.
• Prefer exemptions over disabling. If a guard is blocking something legitimate, create a targeted exemption for that specific skill or channel rather than turning the guard off entirely.
• The audit log is your source of truth. Every detection includes the guard name, detection label, action taken, and timestamp. Start here whenever something isn't working as expected.
• Suppressions are temporary by design. Use them for known false positives while you refine settings, not as a long-term solution.
• Check across guards. If you see events from multiple guards around the same time, it may indicate a real threat rather than a false positive. Look at the full timeline before dismissing detections.