# Gatekeeper - Customer Guide
## How to Use Gatekeeper to Protect Your AI App

**Website:** https://gatekeeper-eta-olive.vercel.app

---

## What is Gatekeeper?

Gatekeeper sits between your app and OpenAI/Anthropic.
Point your AI requests at the Gatekeeper proxy endpoint instead of
calling the provider directly. Your AI is now enterprise-safe.

```
Your App → Gatekeeper → OpenAI / Anthropic
```

Every request gets:
- ✅ PII stripped automatically
- ✅ Jailbreaks blocked
- ✅ SOC-2 / HIPAA compliance enforced
- ✅ Full audit trail logged
- ✅ Instant Slack alerts when blocked
- ✅ Plain English explanation if blocked

---

## Step 1 - Create Your Account

1. Go to https://gatekeeper-eta-olive.vercel.app
2. Click **"Try it free"** button
3. Sign up with your email and password
4. You'll land on the Dashboard

---

## Step 2 - Create Your App

1. Click **Settings** in the left sidebar
2. Fill in the form:

   **App Name:** Enter your app or company name

   **Industry:** Select from dropdown:
   - **SaaS / General** → SOC-2 policy assigned automatically
   - **Healthcare** → HIPAA policy assigned automatically
   - **Finance** → SOC-2 policy assigned automatically

3. Click **"+ Create App"**

4. You'll see your credentials on the right:
   ```
   app_id:  app_xxxxxxxxxxxx
   api_key: gk_live_xxxxxxxxxxxx
   policy:  soc2 (or hipaa)
   ```

⚠️ **Save your api_key - you'll need it every time!**

---

## Step 3 - Connect Your App

After creating your app you'll see the **Next Steps** section
with ready-to-use code snippets!

### For OpenAI Users:

```python
import requests

response = requests.post(
    "https://gatekeeper-production-7dd1.up.railway.app/proxy/openai",
    json={
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": your_message}],
        "max_tokens": 300
    },
    headers={
        "Authorization": "Bearer your-openai-key",
        "X-Gatekeeper-Key": "gk_live_xxxxxxxxxxxx",
        "Content-Type": "application/json"
    }
)
```

### For Anthropic Users:

```python
response = requests.post(
    "https://gatekeeper-production-7dd1.up.railway.app/proxy/anthropic",
    json={
        "model": "claude-haiku-4-5-20251001",
        "messages": [{"role": "user", "content": your_message}],
        "max_tokens": 300
    },
    headers={
        "X-Api-Key": "your-anthropic-key",
        "X-Gatekeeper-Key": "gk_live_xxxxxxxxxxxx",
        "Content-Type": "application/json"
    }
)
```

That's it! **Two changes. Your AI is now protected.**

ℹ️ **POST directly to the proxy endpoint** (`/proxy/openai` or
`/proxy/anthropic`) as shown above. You **cannot** simply set this URL
as the `base_url` in the OpenAI/Anthropic SDK — Gatekeeper wraps the
provider's reply in an envelope (see **Understanding the Response**
below) that the SDK can't parse.

---

## Step 4 - Try the Live Demo

Before connecting your app, try the live demo:

1. Go to the landing page
2. Scroll to **"Live Demo"** section
3. Paste any text with sensitive data:

```
My email is john@gmail.com and SSN is 123-45-6789
```

You'll instantly see:
- What gets redacted
- What types of PII were found
- The cleaned version sent to AI

---

## Step 5 - Run Automated Tests

Go to **Dashboard → Test Suite** to verify everything works:

1. Click **"▶ Run All Tests"** button
2. Watch 11 tests run automatically
3. Tests cover:
   - Email, SSN, Phone, Credit Card, API Key detection
   - Multiple PII combined
   - Clean text (no PII)
   - Normal proxy request
   - PII redaction via proxy
   - Jailbreak blocking
   - IOC threat blocking

4. See results in a table with PASS/FAIL for each test

⚠️ **Note:** Results adjust based on your policy automatically!
- SOC-2 → PII is redacted, request allowed
- HIPAA → PII detected, request blocked

---

## Step 6 - Monitor Your Dashboard

After making requests, go to **Dashboard → Overview**:

| Card | What it shows |
|---|---|
| Requests Today | How many AI calls were made today |
| PII Redacted | How many sensitive items were protected |
| Jailbreaks Blocked | How many attack attempts were caught |
| Cost Saved | Estimated savings from blocked requests |

The **Real-Time Feed** shows your last 10 requests with:
- ✅ ALLOWED - request went through (PII redacted)
- 🚫 BLOCKED - request was stopped (jailbreak/IOC/policy)

---

## Step 7 - View Your Audit Log

Go to **Dashboard → Audit Log** to see every request:

**Features:**
- Full table of all requests with timestamps
- Click any row → see original vs sanitized request
- Filter by **Blocked only** or **PII only**
- Export to CSV for your records
- **Download 30-day SOC-2 report** → PDF for auditors
- **Download 90-day SOC-2 report** → extended PDF

---

## Step 8 - Configure Your Policies

Go to **Dashboard → Policies**:

### Compliance Packs
Toggle ON/OFF pre-built compliance rule sets:

**SOC-2 Compliance Pack** (for SaaS / Finance):
- Redacts PII before sending to AI
- Logs all requests
- Blocks jailbreak attempts
- Rate limits excessive requests

**HIPAA Pack** (for Healthcare):
- Blocks requests containing patient data entirely
- Logs all requests
- Blocks jailbreak attempts
- Blocks medical record data

### Custom Rules (Active Rules)
Build your own rules visually:
```
IF request contains [Email]
THEN [Redact / Block]
```
Click **"+ Add Custom Rule"** → set conditions → **Save Policies**

### Policy as Code (Advanced)
For technical teams - version-control your compliance rules:

1. Create a `gatekeeper.yaml` file in a public GitHub repo:
```yaml
version: 1
base_policy: soc2
custom_rules:
  - id: no-competitor-mentions
    action: redact
    patterns: ["CompetitorA", "CompetitorB"]
```

2. Go to **Policies → Policy as Code** section
3. Paste the GitHub raw URL
4. Click **Register Policy**
5. Rules auto-update every 60 seconds!

---

## Step 9 - Set Up Slack Alerts

Get instant Slack notifications whenever Gatekeeper blocks a request!

### Get Your Slack Webhook URL

1. Go to **https://api.slack.com/apps**
2. Click **"Create New App"** → From scratch
3. Name it: "Gatekeeper Alerts"
4. Select your Slack workspace
5. Click **"Incoming Webhooks"** in the left sidebar
6. Toggle **ON**
7. Click **"Add New Webhook to Workspace"**
8. Select the channel to receive alerts (e.g. #gatekeeper-alerts)
9. Click **Allow**
10. Copy the webhook URL shown

### Connect Slack in Gatekeeper

1. Go to **Dashboard → Settings**
2. Scroll to **"Slack Alerts"** section
3. Paste your webhook URL
4. Click **"Connect"**
5. Click **"Send Test Alert"** to verify it works

You'll see a message in your Slack channel! ✅

### What Alerts Look Like in Slack

```
🚨 Gatekeeper: Jailbreak Detected

App: Your App Name
Time: 2026-05-20 22:14 UTC
Reason: Obvious jailbreak detected by pattern matching

[View in Dashboard]
```

**Rate limiting:** Max 1 alert per minute per reason.
So if 10 jailbreaks happen in 30 seconds → only 1 Slack message!

---

## Step 10 - Test the Proxy Directly

On the **Overview page** you can test the proxy directly:

### Test Proxy OpenAI
1. Your Gatekeeper key is auto-filled
2. Enter your OpenAI API key
3. Select model (gpt-4o-mini recommended)
4. Type your prompt → Click **Send**

### Test Proxy Anthropic
Same as above but with your Anthropic API key!

---

## Step 11 - Workato Integration (Enterprise)

If your team uses Workato for automation:

1. Go to **Dashboard → Integrations**
2. Click **"Request Workato Connector Access →"**
3. This opens an email to dilip@shaachi.com
4. Click Send - our team will share the connector with you!
5. Once you receive access, open the connector in Workato
6. Create a new connection and fill in:
   - **Gatekeeper URL:** `https://gatekeeper-production-7dd1.up.railway.app` (pre-filled!)
   - **Gatekeeper API Key:** `gk_live_xxxxxxxxxxxx` (pre-filled!)
   - **OpenAI API Key:** enter your own key (optional)
7. Click **Connect** → Done! ✅

**Available actions in Workato:**
- **Scan Text for PII** - Scan any text for PII without sending to AI. Free and instant!
- **Send OpenAI Message (Protected)** - Route your AI message through Gatekeeper security proxy

**Example Workato recipe:**
```
Trigger: New support email received
Action 1: Scan Text for PII (Gatekeeper)
Action 2: Send cleaned text to AI
Action 3: Send AI response to agent
```

---

## Understanding the Response

Every proxy call returns a JSON **body** with **exactly two top-level keys**:

```json
{
  "gatekeeper": { "...": "audit metadata" },
  "response":   { "...": "raw provider reply" }
}
```

- **`gatekeeper`** — Gatekeeper's audit metadata for this request (fields below).
- **`response`** — the raw, untouched JSON reply from OpenAI or Anthropic.
  This is **`null` when the request was blocked**.

All Gatekeeper data lives in the response **body** — there are no
`X-Gatekeeper-*` verdict headers to read.

### Allowed request (PII redacted)

```json
{
  "gatekeeper": {
    "provider": "openai",
    "model": "gpt-4o",
    "app_id": "app_abc123",
    "latency_ms": 1840,
    "pii_detected": true,
    "pii_found": [{ "type": "EMAIL_ADDRESS", "score": 0.99 }],
    "pii_count": 1,
    "jailbreak_detected": false,
    "jailbreak_score": 0,
    "policy": "soc2",
    "policy_action": "redact",
    "policy_violations": [],
    "blocked": false,
    "original_text": "My email is john@gmail.com",
    "cleaned_text": "My email is [REDACTED_EMAIL_ADDRESS]"
  },
  "response": { "...": "raw OpenAI / Anthropic reply" }
}
```

### Blocked request

```json
{
  "gatekeeper": {
    "provider": "openai",
    "model": "gpt-4o",
    "app_id": "app_abc123",
    "latency_ms": 312,
    "pii_detected": false,
    "pii_found": [],
    "pii_count": 0,
    "jailbreak_detected": true,
    "jailbreak_score": 100,
    "jailbreak_reason": "Obvious jailbreak detected by pattern matching",
    "policy": "soc2",
    "policy_violations": [],
    "blocked": true,
    "block_reason": "Obvious jailbreak detected by pattern matching",
    "explanation": "Your request was blocked because it appeared to attempt bypassing security rules.",
    "original_text": "<full user message>",
    "cleaned_text": null
  },
  "response": null
}
```

### Key fields in the `gatekeeper` block

| Field | Meaning |
|---|---|
| `blocked` | `true` if the request was stopped (then `response` is `null`) |
| `block_reason` | Why it was blocked (present when `blocked` is `true`) |
| `policy_action` | What the policy did to an allowed request (e.g. `redact`) |
| `policy_violations` | List of policy rules that matched |
| `pii_detected` / `pii_found` / `pii_count` | Whether PII was found, the matches, and how many |
| `jailbreak_detected` / `jailbreak_score` | Jailbreak verdict and 0–100 score |
| `original_text` / `cleaned_text` | The input and the redacted version sent upstream (`cleaned_text` is `null` when blocked) |
| `latency_ms` | Total end-to-end time, dominated by the upstream provider call |

**Why requests get blocked:**
| Reason | What happened |
|---|---|
| Jailbreak detected | Prompt tried to manipulate the AI |
| IOC match | Known malicious pattern detected |
| HIPAA violation | Patient health information detected |
| Custom rule triggered | Your custom policy blocked it |
| Rate limit exceeded | Too many requests (upgrade plan) |

---

## Security Features Explained

### PII Detection
Automatically detects and redacts:
- Email addresses → [REDACTED_EMAIL_ADDRESS]
- Phone numbers → [REDACTED_PHONE_NUMBER]
- SSN → [REDACTED_SSN]
- Credit cards → [REDACTED_CREDIT_CARD]
- API keys → [REDACTED_API_KEY]
- Names → [REDACTED_PERSON]
- Addresses → [REDACTED_ADDRESS]

### Jailbreak Detection
Two-layer system:
1. Fast regex check (<1ms) - catches obvious attacks
2. AI judge check (~2s) - catches subtle attacks

### IOC Threat Intelligence
Threat-intelligence checks for known malicious patterns and domains
in your traffic.

### Slack Alerts
Instant notifications when requests are blocked.
Rate limited to 1 alert per minute per reason.
Never includes original prompt content - only metadata.

---

## Pricing Plans

| Feature | Free | Pro ($200/mo) |
|---|---|---|
| Requests/month | 10,000 | Unlimited |
| Apps | 1 | Unlimited |
| Policy packs | SOC-2 only | SOC-2 + HIPAA |
| Audit logs | 30 days | 90 days |
| SOC-2 report | ✅ | ✅ |
| Custom rules | 3 | Unlimited |
| Slack alerts | ✅ | ✅ |
| Workato integration | ✅ | ✅ |
| Support | Community | Priority |

---