Configuration

CrabShield is configured through the CrabShack dashboard. All changes are applied automatically — you don't need to restart anything or edit files manually.

Accessing Security Settings

1. Open the CrabShack dashboard
2. Navigate to Security in the sidebar
3. You'll see all 18 guards listed with their current status

From here you can enable/disable guards, change modes, and adjust settings.

Guard Modes

When configuring a guard, you'll choose a mode that determines how it responds to threats:

Block

The strictest mode. When a threat is detected, the message or action is stopped entirely. The user sees a generic security message — no details about what was detected or why.

Best for: High-confidence threats where you want zero tolerance, like system prompt extraction attempts.

Sanitize

A balanced approach. The message is allowed through, but the threatening content is neutralized. The agent sees a cleaned version of the message.

Best for: Guards where you want protection without disrupting conversations, like prompt injection.

Warn

The message goes through unchanged, but the event is logged as a warning. You can review warnings in the audit log.

Best for: Monitoring mode — use this when you're tuning a guard and want to see what it catches before turning on blocking.

Log

The lightest mode. Events are recorded for analytics, but no action is taken.

Best for: Baselining — understanding normal patterns before deciding on a stricter mode.

Exemptions

Sometimes a trusted skill or channel needs to do something that a guard would normally flag. Rather than disabling the entire guard, you can create exemptions for specific contexts.

Exemptions have three context types:

Context	Format	Example
Skill	Skill name (string)	backup-skill
Channel	Channel ID (string)	internal-ops
Scheduled task	Cron job name (string)	nightly-report

Finding the right values

Not sure what skill name or channel ID to use? Go to Security > Audit Log, find the event that blocked your action, and click on it to expand the details. The skill name, channel ID, and session key are shown there — you can use these values directly when creating your exemption.

Exemption Examples

Tool Gate — allow a backup skill to use tools that are normally blocked:

{
  "skillName": "backup-skill",
  "tools": ["exec", "fs_delete"],
  "raiseRateLimit": 200,
  "disableSequenceAnalysis": true
}

Network Policy — allow a specific skill to reach an external API:

{
  "skillName": "weather-skill",
  "allowedHosts": ["api.weather.com", "*.openweathermap.org"],
  "allowedPorts": [443]
}

Credential Vault — skip PII scanning for an internal analytics channel:

{
  "channelId": "internal-analytics",
  "disablePii": true
}

Exemptions are configured per-guard in the dashboard. They're narrow by design — you exempt a specific skill from a specific check, not everything at once.

Custom Patterns

Several guards let you add custom patterns to catch threats specific to your organization. Custom patterns are regular expressions (regex).

Format

Patterns are entered as an array of regex strings:

["pattern-one", "pattern-two"]

Examples

Prompt Injection — block a specific phrase used in your industry:

["override\\s+compliance\\s+mode", "activate\\s+debug\\s+protocol"]

Credential Vault — catch an internal API key format:

["MYCO-[A-Za-z0-9]{32}"]

Escalation Detection — flag a command specific to your infrastructure:

["deploy\\s+--force\\s+--no-verify"]

tip

Start with broad patterns and narrow them down if you get false positives. Check the audit log to see what your custom patterns are matching.

Testing Custom Patterns

When adding custom patterns, follow this workflow to avoid disrupting your agents:

1. Add the pattern in Warn mode — the guard will log matches without taking action
2. Monitor the audit log for a few days to see what the pattern catches
3. Refine the pattern if it's too broad or too narrow
4. Switch to Block or Sanitize once you're confident the pattern is accurate

Common regex pitfalls to watch for:

• Missing word boundaries — admin will match "administrator" and "sysadmin". Use \badmin\b if you only want the exact word.
• Overly broad patterns — key will match "keyboard", "turkey", and every other word containing "key". Be as specific as possible.
• Case sensitivity — patterns are case-sensitive by default. If you want to match both "Password" and "password", include both cases or use the appropriate flag.
• Special characters — characters like ., *, (, and ) have special meaning in regex. Escape them with \ if you want to match them literally.

tip

After creating an exemption, monitor the audit log for a few days to confirm it's working as expected. An exemption that's too broad can create a gap in your protection.

Suppression System

If a guard is producing false positives for a specific detection, you can suppress it rather than disabling the entire guard:

• Suppressions target a specific detection label (shown in the audit log)
• Each suppression has an expiry time — they're temporary by design
• Expired suppressions are cleaned up automatically

This lets you acknowledge known safe patterns without reducing your overall protection.

Default Profiles

Secure Defaults

Every fresh CrabShack installation starts with Secure Defaults:

Guard	Default Mode
Prompt Injection	Sanitize
System Prompt Leakage	Block
Tool Gate	Block
Escalation Detection	Warn
Output Scanner	Warn
All other guards	Enabled with default settings

This gives you strong protection out of the box without being so strict that it disrupts normal use.

Lockdown Mode

If CrabShield detects a configuration integrity issue, it automatically switches to Lockdown Mode:

• Prompt Injection, Escalation Detection, and Output Scanner escalate to Block
• Tool Gate tightens rate limits and destructive action thresholds
• Input Validator reduces message size and rate limits

This fail-safe ensures your agents are always protected, even if something goes wrong with configuration delivery.

Operational Best Practices

Monitoring Guard Effectiveness

Review the audit log weekly to understand how your guards are performing:

• Look for trends — are detections increasing or decreasing over time? A spike may indicate a new threat; a steady decline may mean your custom patterns are working.
• Check for gaps — are there guards that never fire? This could mean they're well-configured, or it could mean the threats they protect against haven't been tested in your environment.
• Review suppressions — check whether any suppressions have expired or need renewal. Suppressions that keep getting renewed may indicate a need for a custom pattern adjustment instead.

Tuning Over Time

Use the warn-then-block pattern when making changes:

1. Set a guard to Warn mode to establish a baseline of what it catches
2. Review detections over several days to identify false positives
3. Create suppressions or adjust patterns for false positives
4. Switch to Block or Sanitize once you're confident in the guard's accuracy

This approach gives you data-driven confidence before enforcing stricter policies.

Responding to Real Threats

When you see a suspicious detection in the audit log:

• Check the timeline — look for events from other guards around the same time. A real attack often triggers multiple guards.
• Review the full session — a single detection may be part of a larger pattern. Check the session's event history for context.
• Escalate if needed — if you see coordinated events across multiple guards (e.g., prompt injection followed by tool usage followed by network requests), this may indicate an active attack.

Exemption Governance

Keep your exemptions well-managed:

• Scope exemptions narrowly — exempt a specific skill from a specific guard check, not everything at once
• Document the reason — note why each exemption was created so future administrators understand the decision
• Review periodically — check whether exemptions are still needed. Skills get updated, workflows change, and an exemption that was necessary six months ago may no longer be required
• Monitor after creation — watch the audit log after adding an exemption to confirm it's not creating a gap in your protection

Tips

• Start with defaults. CrabShield's out-of-the-box settings are designed to protect against the most common threats without false positives.
• Use warn mode first. When enabling a new guard or tightening settings, start in warn mode to see what it catches, then switch to block or sanitize once you're confident.
• Use exemptions, not disabling. If a guard is blocking something legitimate, create a targeted exemption rather than turning the guard off entirely.
• Check the audit log. The Security > Audit Log section shows all events across all guards. Use it to understand what CrabShield is seeing and to tune your settings.
• Suppressions are temporary. Use them for known false positives while you refine your custom patterns, not as a long-term fix.