Pre Publish Security

Multi-layered security audit system for GitHub/ClawHub releases. Prevents credential leaks, detects vulnerabilities, validates documentation. Frequency-aware...

Security Scan

The skill generally matches its stated purpose (pre-publish repo audits) but there are a few mismatches and risky operational behaviours you should understand before installing (undeclared CLI dependency, interactive blocking hooks, and some brittle state handling).

Purpose & Capability

The scripts and agent task files implement repository scanning, history scans, dependency checks, and hook installation which aligns with the skill's description. However, audit.sh invokes the external CLI command openclaw (openclaw sessions spawn) but the binary 'openclaw' is not declared in the required binaries list. If the runtime does not already provide this CLI, the orchestrator portion will fail. Otherwise the overall requested capabilities are proportionate to the described purpose.

Instruction Scope

The runtime instructions and scripts install a Git pre-push hook that will run the audit and block pushes on CRITICAL/HIGH issues — this is expected for the stated goal but is high-impact. The pre-push hook runs audit.sh which spawns subagents via the openclaw CLI; if that CLI is present it will execute generated agent tasks. Several scripts (audit-simple.sh and audit.sh) prompt interactively on HIGH issues (read -r response), which can hang non-interactive workflows/CI or surprise users. The agent task definitions claim to consider credential stores (e.g., ~/.git-credentials) in descriptions, but commands operate inside the provided target path; they do not appear to scan user home files unless the repo path includes them.

Install Mechanism

This is instruction-only with bundled shell scripts; there is no remote download/install step beyond an apt suggestion for jq in SKILL.md. No external archives or short URLs are fetched. Risk from install-time network downloads is low.

Credentials

The skill requests no secret environment variables and primarily reads/writes files in the user's repo and its own state under $HOME/.openclaw/workspace/skills/pre-publish-security. That is proportionate for a repo scanner. It will call optional tools (npm, safety, shellcheck) if present; npm audit/safety may perform network operations. The skill does not itself declare or require credentials, nor does it explicitly exfiltrate data to external endpoints.

Persistence & Privilege

The tool installs Git hooks (modifies .git/hooks/pre-push) and writes a state file under ~/.openclaw/workspace/skills/... which is expected behavior for a repository hook/auditor. It is not always:true and does not modify other skills' configs. Because it can block pushes, users should be aware of the high operational privilege implicit in installing pre-push hooks.

What to consider before installing

This skill appears to implement the pre-publish audits it advertises, but review the following before installing: - Confirm your environment provides the openclaw CLI: audit.sh uses 'openclaw sessions spawn' but 'openclaw' is not listed in required binaries. If openclaw is missing the hook/orchestrator will fail. - Expect the installer to write a pre-push hook into each repo's .git/hooks/pre-push; that hook will run the audit and can block pushes. Test the hook in a disposable repository first. - The scripts prompt interactively on HIGH issues (read -r response). That may hang non-interactive environments (CI). If you plan to run in CI, remove/adjust interactive prompts or run a non-interactive mode. - The tool writes state under $HOME/.openclaw/workspace/skills/pre-publish-security and stores reports in /tmp; verify you are comfortable with these files and their retention. - There are some fragile implementation details (jq updates to counters may fail if state keys are absent), so run the scripts manually to observe behavior before enabling automatic hooks/cron. - Audit network behaviour for your use: npm audit and safety (if used) perform network lookups; the tool itself does not appear to exfiltrate findings to remote endpoints, but audit.sh will spawn subagents via the openclaw CLI which will execute the included agent tasks — inspect those task templates and ensure you trust the local openclaw runtime. If you lack confidence in any of the above, review the shipped scripts line-by-line or run them in a sandboxed/test repository. If you proceed, remove interactive prompts or configure non-interactive operation for CI environments.

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

1. Individual Developers: Pre-push hook prevents accidents
2. Open-Source Projects: Protects against contributor mistakes
3. ClawHub Skills: Validates before publishing
4. CI/CD: Add to GitHub Actions for automated checks
5. 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