Pre-Publish Security Protocol

Prevents security breaches like exposed credentials in open-source releases.

Features

✅ Multi-Level Scanning

Quick scan: Every push (~5s)
History scan: Monthly deep dive (~2-5min)
Dependency CVE: Weekly npm/Python check (~30s)
Full audit: On-demand comprehensive (~3-6min)

✅ Smart Frequency Management

State tracking knows when each scan last ran
Auto-determines which scans to run
Prevents redundant checks

✅ What It Catches

GitHub PATs, API keys, passwords, private keys
Secrets in git history (even if "deleted")
npm/Python dependency CVEs
Unsafe code patterns (eval, exec)
Documentation placeholders ([ORG], example.com)
Missing LICENSE/README files
Exported environment variables with secrets

✅ Automated Protection

Git pre-push hook blocks bad commits
Severity-based exit codes (CRITICAL/HIGH/MEDIUM/LOW)
Markdown reports with actionable fixes

Quick Start

Install Pre-Push Hook

# Automatic protection on every push
./install-hooks.sh /path/to/your/repo

Run First History Scan

# One-time deep dive (or monthly)
./audit-full.sh /path/to/repo history

Check Status

# See when scans last ran
./schedule.sh status

Run Scheduled Audits

# Auto-determines what to run based on time
./schedule.sh run /path/to/repo

Manual Scans

# Quick scan (every push)
./audit-simple.sh /path/to/repo

# Git history scan (monthly)
./audit-full.sh /path/to/repo history

# Dependency scan (weekly)
./audit-full.sh /path/to/repo dependencies

# Full audit (before releases)
./audit-full.sh /path/to/repo full

What Gets Scanned

Quick Scan (Every Push)

Current file secret patterns
Documentation placeholders
Basic license/README presence
Runtime: ~5 seconds

History Scan (Monthly)

Full git commit history
Deleted-but-accessible credentials
Historical security issues
Runtime: 2-5 minutes

Dependency Scan (Weekly)

npm audit (Node.js CVEs)
Python safety check
Known vulnerabilities
Runtime: ~30 seconds

Full Audit (On-Demand)

All of the above
Environment variable leaks
Pre-commit hook verification
Code quality patterns
Runtime: 3-6 minutes

Severity Levels

CRITICAL → Blocks push (secrets, credentials)
HIGH → Requires approval (vulnerabilities, missing LICENSE)
MEDIUM → Warning (TODOs, missing README)
LOW → Informational

Integration

Pre-Push Hook (Recommended)

./install-hooks.sh ~/my-repo
git push  # Automatic security check

Weekly Cron

# Add to OpenClaw cron
openclaw cron add \
  --name "weekly-repo-scan" \
  --cron "0 3 * * 1" \
  --announce \
  --message "Run: ~/.openclaw/workspace/skills/pre-publish-security/schedule.sh run ~/repo"

Manual Pre-Publish

# Before clawhub publish
./audit-full.sh ~/skills/my-skill full
clawhub publish skills/my-skill --version 1.0.1

Files

audit-simple.sh - Fast pre-push scan
audit-full.sh - Complete scanner with tracking
schedule.sh - Status & smart automation
install-hooks.sh - Git hook installer
audit-state.json - State tracking (auto-created)
AUDIT-SCHEDULE.md - Detailed frequency guide
README.md - Full documentation
agents/ - Sub-agent definitions (future use)

Requirements

Required:

git
jq
grep

Optional (enhanced detection):

npm (Node.js dependency scanning)
pip + safety (Python dependency scanning)
shellcheck (bash script validation)

State Tracking

Automatically tracks:

Last run timestamp for each scan type
Total scan counts
Cumulative findings by severity

View with: ./schedule.sh status

Exit Codes

0 - Passed (no issues or low/medium only)
1 - Critical issues (blocks push)
2 - High issues (requires review)

Real-World Example

Problem: Accidentally pushed GitHub PAT in git remote URL
Solution: This tool caught it and blocked the push
Result: Credential never exposed publicly

Use Cases

Individual Developers: Pre-push hook prevents accidents
Open-Source Projects: Protects against contributor mistakes
ClawHub Skills: Validates before publishing
CI/CD: Add to GitHub Actions for automated checks
Security Audits: Comprehensive repository review

Why This Exists

On 2026-03-15, a GitHub PAT was accidentally exposed in a git config file. This protocol ensures it never happens again - to anyone.

License

MIT - Use it, improve it, share it.

Contributing

Issues & PRs welcome at: https://github.com/solmas/pre-publish-security