Lesson 4.4: Security Review Before You Share

🎯 What You'll Learn: How to catch security issues before they become incidents, credentials, access scope, and what your toolkit touches
⏱️ Time Required: 35 minutes

---

Riley's Near-Miss

Riley was doing a final read-through before sending the toolkit to David. She saw it: her actual Slack bot token, right there in a README example.

"Anyone who installed my toolkit would have had my company Slack credentials. I'd been so focused on making it work that I never looked at it through the lens of 'what if someone else reads this?' Security review isn't optional. It's the last line before distribution."
— Riley Harper

This lesson is a systematic pass through your toolkit to catch anything like this before it ships.

---

What You're Looking For

Three categories of risk:

1. Hardcoded secrets, API keys, tokens, webhook URLs embedded directly in files. If they end up in a shared folder, email, or GitHub repo, they're compromised.

2. Personal paths, /Users/Riley/ or C:\Users\Riley\ embedded in scripts, configs, or templates. These break on any machine that isn't yours and leak information about your system layout.

3. Over-permissioned access, MCP servers configured with access to your entire home directory instead of only the folders the toolkit needs.

---

Exercise: Security Audit (35 min)

Step 1: Scan for Secrets (10 min)

Run these commands from inside your toolkit folder:

# Slack tokens
grep -r "xoxb-" .
grep -r "hooks.slack.com" .

# Generic API key patterns
grep -r -i "api_key\|apikey\|api-key" .
grep -r -i "secret\|password\|token" .

# AWS, OpenAI, Anthropic
grep -r "sk-" .
grep -r "AKIA" .

# Personal paths
grep -r "/Users/" .
grep -r "C:\\\\Users" .

# Real email addresses
grep -r -E "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}" . --include="*.md"

Any result that isn't a placeholder or documentation about credentials is a problem.

The fix is always one of two things:

Replace real values with environment variable references in code:

{ "slack_token": "${SLACK_BOT_TOKEN}" }

Replace real values with clearly fake placeholders in documentation:

export SLACK_BOT_TOKEN="xoxb-YOUR-TOKEN-HERE"

Riley's audit findings:

Step 2: Fix MCP Permissions (10 min)

If your toolkit includes an MCP server config (in hooks/settings-snippet.json or a config template), check the filesystem scope.

Too broad, exposes everything:

{
  "filesystem": {
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "~"]
  }
}

Correct, scoped to what the toolkit actually needs:

{
  "filesystem": {
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "${PRIME_BROKER_EXPORT_DIR}",
      "${REPORTS_DIR}"
    ]
  }
}

The principle: request access to the minimum number of paths the toolkit needs to function. The installer should set those paths explicitly, never grant access to ~ or /.

For API permissions (Slack, etc.), document exactly which scopes you need and why you need each one:

## Required Slack Scopes
- `chat:write` — to post the report to a channel
- `channels:read` — to verify the channel exists before posting

We don't need admin, user data, or file management permissions.

Step 3: Create a SECURITY.md (10 min)

Add a SECURITY.md to your toolkit root that documents what the toolkit touches. This helps installers make informed decisions, and it signals you've thought about it.

Template:

# Security Information

## What This Toolkit Accesses

### File System
- Read: `PRIME_BROKER_EXPORT_DIR` (Prime Broker portal CSV exports)
- Write: `REPORTS_DIR` (generated report files)

We do NOT access your home directory root, system folders, or any other application data.

### External APIs
- **Slack** — posts to one configured channel (`chat:write` scope only)

We do NOT store data externally, send data to third parties, or require admin privileges on any system.

## Credential Handling

| Credential | Where it's stored |
|------------|------------------|
| `SLACK_BOT_TOKEN` | Environment variable only — never in any file |
| `SLACK_TEAM_ID` | Environment variable only |

## Reporting Issues

If you find a security problem: [your contact method]

Step 4: Final Check Before Sharing (5 min)

Run one final scan, then sign off:

# Should return nothing if your toolkit is clean
grep -r -E "(xoxb|sk-|AKIA|hooks\.slack\.com)" .
grep -r "/Users/[A-Za-z]" .
grep -r "C:\\\\Users\\\\[A-Za-z]" .

Checklist:

If everything is clean, the toolkit is ready to share.

---

The Cost of Getting This Wrong

"The security review took 45 minutes. Finding an exposed token in a shared internal repo would have taken months to sort out. 45 minutes for peace of mind is one of the best trades I've made."
— Riley Harper

---

✅ Success Criteria:

---

Next Up

You've built, documented, and reviewed a shareable toolkit. Your automation is ready for the rest of the course, and for the rest of your team.